Boost C++ 库

...是世界上最受推崇和设计最精良的 C++ 库项目之一。 — Herb Sutter 和 Andrei Alexandrescu, C++ 编码标准

Boost.Assert 库提供了几个可配置的诊断宏，其行为和目的类似于 <cassert> 中的标准宏 assert。

断言宏, <boost/assert.hpp>

BOOST_ASSERT

头文件 <boost/assert.hpp> 定义了宏 BOOST_ASSERT，它类似于 <cassert> 中定义的标准 assert 宏。该宏旨在用于 Boost 库和用户代码中。

默认情况下，BOOST_ASSERT(expr) 展开为 assert(expr)。
如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_DISABLE_ASSERTS，则 BOOST_ASSERT(expr) 展开为 ((void)0)，而无论是否定义了宏 NDEBUG。这允许用户有选择地禁用 BOOST_ASSERT，而不会影响标准 assert 的定义。
如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_ENABLE_ASSERT_HANDLER，则 BOOST_ASSERT(expr) 展开为
```
(BOOST_LIKELY(!!(expr))? ((void)0): ::boost::assertion_failed(#expr,
    BOOST_CURRENT_FUNCTION, __FILE__, __LINE__))
```
也就是说，它计算 expr，如果为 false，则调用 ::boost::assertion_failed(#expr, BOOST_CURRENT_FUNCTION, __FILE__, __LINE__)。无论是否定义了 NDEBUG，情况都是如此。

boost::assertion_failed 在 <boost/assert.hpp> 中声明为
```
namespace boost
{
    void assertion_failed(char const * expr, char const * function,
        char const * file, long line);
}
```
但它从未被定义。用户需要提供适当的定义。
如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_ENABLE_ASSERT_DEBUG_HANDLER，则当定义了 NDEBUG 时，BOOST_ASSERT(expr) 展开为 ((void)0)。否则，其行为就像定义了 BOOST_ENABLE_ASSERT_HANDLER 一样。

与 <cassert> 一样，<boost/assert.hpp> 可以在单个翻译单元中包含多次。 BOOST_ASSERT 将按照上述指定进行重新定义。

BOOST_ASSERT_MSG

宏 BOOST_ASSERT_MSG 与 BOOST_ASSERT 类似，但它接受一个额外的参数，即一个字符文字，提供错误消息。

默认情况下，BOOST_ASSERT_MSG(expr,msg) 展开为 assert((expr)&&(msg))。
如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_DISABLE_ASSERTS，则 BOOST_ASSERT_MSG(expr,msg) 展开为 ((void)0)，而无论是否定义了宏 NDEBUG。

如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_ENABLE_ASSERT_HANDLER，则 BOOST_ASSERT_MSG(expr,msg) 展开为

(BOOST_LIKELY(!!(expr))? ((void)0): ::boost::assertion_failed_msg(#expr,
    msg, BOOST_CURRENT_FUNCTION, __FILE__, __LINE__))

无论是否定义了 NDEBUG，情况都是如此。

boost::assertion_failed_msg 在 <boost/assert.hpp> 中声明为

namespace boost
{
    void assertion_failed_msg(char const * expr, char const * msg,
        char const * function, char const * file, long line);
}

但它从未被定义。用户需要提供适当的定义。

如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_ENABLE_ASSERT_DEBUG_HANDLER，则当定义了 NDEBUG 时，BOOST_ASSERT_MSG(expr) 展开为 ((void)0)。否则，其行为就像定义了 BOOST_ENABLE_ASSERT_HANDLER 一样。

与 <cassert> 一样，<boost/assert.hpp> 可以在单个翻译单元中包含多次。 BOOST_ASSERT_MSG 将按照上述指定进行重新定义。

BOOST_VERIFY

宏 BOOST_VERIFY 的行为与 BOOST_ASSERT 相同，只是传递给 BOOST_VERIFY 的表达式始终会被计算。当断言的表达式具有期望的副作用时，这非常有用；它还可以帮助在使用变量的唯一位置在断言内部时，抑制关于未使用变量的警告。

如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_DISABLE_ASSERTS，则 BOOST_VERIFY(expr) 展开为 ((void)(expr))。
如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_ENABLE_ASSERT_HANDLER，则 BOOST_VERIFY(expr) 展开为 BOOST_ASSERT(expr)。
否则，当定义了 NDEBUG 时，BOOST_VERIFY(expr) 展开为 ((void)(expr))，当没有定义 NDEBUG 时，展开为 BOOST_ASSERT(expr)。

BOOST_VERIFY_MSG

宏 BOOST_VERIFY_MSG 与 BOOST_VERIFY 类似，但有一个额外的参数，即错误消息。

如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_DISABLE_ASSERTS，则 BOOST_VERIFY_MSG(expr,msg) 展开为 ((void)(expr))。
如果在包含 <boost/assert.hpp> 时定义了宏 BOOST_ENABLE_ASSERT_HANDLER，则 BOOST_VERIFY_MSG(expr,msg) 展开为 BOOST_ASSERT_MSG(expr,msg)。
否则，当定义了 NDEBUG 时，BOOST_VERIFY_MSG(expr,msg) 展开为 ((void)(expr))，当没有定义 NDEBUG 时，展开为 BOOST_ASSERT_MSG(expr,msg)。

BOOST_ASSERT_IS_VOID

当 BOOST_ASSERT 和 BOOST_ASSERT_MSG 展开为 ((void)0) 时，定义宏 BOOST_ASSERT_IS_VOID。其目的是避免编译和潜在地运行仅用于准备在断言中使用的数据的代码。

void MyContainer::erase(iterator i)
{
// Some sanity checks, data must be ordered
#ifndef BOOST_ASSERT_IS_VOID

    if(i != c.begin()) {
        iterator prev = i;
        --prev;
        BOOST_ASSERT(*prev < *i);
    }
    else if(i != c.end()) {
        iterator next = i;
        ++next;
        BOOST_ASSERT(*i < *next);
    }

#endif

    this->erase_impl(i);
}

默认情况下，如果定义了 NDEBUG，则定义 BOOST_ASSERT_IS_VOID。
如果定义了宏 BOOST_DISABLE_ASSERTS，则始终定义 BOOST_ASSERT_IS_VOID。
如果定义了宏 BOOST_ENABLE_ASSERT_HANDLER，则永远不会定义 BOOST_ASSERT_IS_VOID。
如果定义了宏 BOOST_ENABLE_ASSERT_DEBUG_HANDLER，则当定义了 NDEBUG 时，定义 BOOST_ASSERT_IS_VOID。

当前函数宏, <boost/current_function.hpp>

BOOST_CURRENT_FUNCTION

头文件 <boost/current_function.hpp> 定义了一个宏 BOOST_CURRENT_FUNCTION，类似于 C99 预定义的标识符 __func__。

BOOST_CURRENT_FUNCTION 展开为字符串字面值，或者包含封闭函数名称（如果可能，则为完全限定的名称）的当前函数的字符数组的名称。如果没有封闭函数，则行为因编译器而异，但通常是编译错误。

某些编译器不提供获取当前封闭函数名称的方法。在这些编译器上，或者当定义了宏 BOOST_DISABLE_CURRENT_FUNCTION 时，BOOST_CURRENT_FUNCTION 展开为 "(unknown)"。

BOOST_DISABLE_CURRENT_FUNCTION 解决了一种用例，在这种用例中，程序员出于安全原因，希望从最终可执行文件中删除 BOOST_CURRENT_FUNCTION 生成的字符串字面值。

源位置支持, <boost/assert/source_location.hpp>

描述

头文件 <boost/assert/source_location.hpp> 定义了 source_location，这是一个表示源位置的类，包含文件、行、函数和列信息。它类似于 C++20 中的 std::source_location，但仅需要 C++03。

宏 BOOST_CURRENT_LOCATION 创建一个 source_location 对象，其中包含有关当前源位置的信息。它可以大致以 std::source_location::current() 的相同方式使用，例如在函数默认参数的声明中

#include <boost/assert/source_location.hpp>
#include <iostream>

void f( boost::source_location const& loc = BOOST_CURRENT_LOCATION )
{
    std::cout << "f() called from: " << loc << std::endl;
}

int main()
{
    f();
}

此示例的输出因编译器和 C++ 标准级别而异，但通常是以下之一

f() called from: example.cpp:11:6 in function 'int main()'

f() called from: example.cpp:11:5 in function 'main'

f() called from: example.cpp:11 in function 'main'

f() called from: example.cpp:4

例如，如果您想声明一个引发异常的函数，使得调用者的源位置附加到引发的异常，这将非常有用

BOOST_NORETURN BOOST_NOINLINE void throw_invalid_argument(
    char const* message,
    boost::source_location const& loc = BOOST_CURRENT_LOCATION )
{
    boost::throw_exception( std::invalid_argument( message ), loc );
}

现在，您可以在例如 at 的实现中使用此辅助函数来发出超出范围的索引的信号

T& my_class::at( size_t i )
{
    if( i >= size() ) throw_invalid_argument( "index out of range" );
    return data()[ i ];
}

这会将 at 中调用 throw_invalid_argument 的行的源位置附加到引发的异常。

请注意，如果相反您在 throw_invalid_argument 中使用 BOOST_THROW_EXCEPTION，则位置将是 throw_invalid_argument 的位置，而不是其调用者的位置。

概要

namespace boost
{

struct source_location
{
    constexpr source_location() noexcept;
    constexpr source_location( char const* file, uint_least32_t line,
      char const* function, uint_least32_t column = 0 ) noexcept;
    constexpr source_location( std::source_location const& loc ) noexcept;

    constexpr char const* file_name() const noexcept;
    constexpr char const* function_name() const noexcept;
    constexpr uint_least32_t line() const noexcept;
    constexpr uint_least32_t column() const noexcept;

    std::string to_string() const;
};

template<class E, class T>
  std::basic_ostream<E, T> &
    operator<<( std::basic_ostream<E, T> & os, source_location const & loc );

} // namespace boost

#define BOOST_CURRENT_LOCATION /* see below */

source_location

constexpr source_location() noexcept;

效果: 构造一个 source_location 对象，该对象的 file_name() 和 function_name() 返回 ""，并且 line() 和 column() 返回 0。

constexpr source_location( char const* file, uint_least32_t line,
  char const* function, uint_least32_t column = 0 ) noexcept;

效果: 构造一个 source_location 对象，该对象的 file_name() 返回 file，function_name() 返回 function，line() 返回 line 参数，并且 column() 返回 column 参数。

constexpr source_location( std::source_location const& loc ) noexcept;

效果: 构造一个 source_location 对象，该对象的 file_name() 返回 loc.file_name()，function_name() 返回 loc.function_name()，line() 返回 loc.line()，并且 column() 返回 loc.column()。

to_string

std::string to_string() const;

返回: *this 的字符串表示形式。

operator<<

template<class E, class T>
  std::basic_ostream<E, T> &
    operator<<( std::basic_ostream<E, T> & os, source_location const & loc );

效果: os << loc.to_string().
返回: os.

BOOST_CURRENT_LOCATION

当定义了 BOOST_DISABLE_CURRENT_LOCATION 时，BOOST_CURRENT_LOCATION 的定义是

#define BOOST_CURRENT_LOCATION ::boost::source_location()

这允许生成不包含任何识别信息的可执行文件，以确保安全。

否则，BOOST_CURRENT_LOCATION 定义为以下内容的近似等效项

#define BOOST_CURRENT_LOCATION \
    ::boost::source_location(::std::source_location::current())

修订历史

1.79.0 版本中的更改

source_location().file_name() 和 source_location().function_name() 现在返回 "" 而不是 "(unknown)"。
添加了从 std::source_location 构造的 source_location 构造函数。
更改了 BOOST_CURRENT_LOCATION 以更紧密地匹配 std::source_location::current() 的行为，例如，可以在顶层或作为默认函数参数使用。

1.78.0 版本中的更改

添加了 source_location::to_string。

1.73.0 版本中的更改

添加了 source_location。

附录 A：版权和许可

本文档的版权归属

根据Boost 软件许可，1.0 版分发。