The Boost.Assert library provides several configurable diagnostic macros similar in behavior and purpose to the standard macro assert from <cassert>.

Assertion Macros, <boost/assert.hpp>

BOOST_ASSERT

The header <boost/assert.hpp> defines the macro BOOST_ASSERT, which is similar to the standard assert macro defined in <cassert>. The macro is intended to be used in both Boost libraries and user code.

  • By default, BOOST_ASSERT(expr) expands to assert(expr).

  • If the macro BOOST_DISABLE_ASSERTS is defined when <boost/assert.hpp> is included, BOOST_ASSERT(expr) expands to ((void)0), regardless of whether the macro NDEBUG is defined. This allows users to selectively disable BOOST_ASSERT without affecting the definition of the standard assert.

  • If the macro BOOST_ENABLE_ASSERT_HANDLER is defined when <boost/assert.hpp> is included, BOOST_ASSERT(expr) expands to

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

    That is, it evaluates expr and if it’s false, calls ::boost::assertion_failed(#expr, BOOST_CURRENT_FUNCTION, __FILE__, __LINE__). This is true regardless of whether NDEBUG is defined.

    boost::assertion_failed is declared in <boost/assert.hpp> as

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

    but it is never defined. The user is expected to supply an appropriate definition.

  • If the macro BOOST_ENABLE_ASSERT_DEBUG_HANDLER is defined when <boost/assert.hpp> is included, BOOST_ASSERT(expr) expands to ((void)0) when NDEBUG is defined. Otherwise the behavior is as if BOOST_ENABLE_ASSERT_HANDLER has been defined.

As is the case with <cassert>, <boost/assert.hpp> can be included multiple times in a single translation unit. BOOST_ASSERT will be redefined each time as specified above.

BOOST_ASSERT_MSG

The macro BOOST_ASSERT_MSG is similar to BOOST_ASSERT, but it takes an additional argument, a character literal, supplying an error message.

  • By default, BOOST_ASSERT_MSG(expr,msg) expands to assert((expr)&&(msg)).

  • If the macro BOOST_DISABLE_ASSERTS is defined when <boost/assert.hpp> is included, BOOST_ASSERT_MSG(expr,msg) expands to ((void)0), regardless of whether the macro NDEBUG is defined.

  • If the macro BOOST_ENABLE_ASSERT_HANDLER is defined when <boost/assert.hpp> is included, BOOST_ASSERT_MSG(expr,msg) expands to

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

    This is true regardless of whether NDEBUG is defined.

    boost::assertion_failed_msg is declared in <boost/assert.hpp> as

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

    but it is never defined. The user is expected to supply an appropriate definition.

  • If the macro BOOST_ENABLE_ASSERT_DEBUG_HANDLER is defined when <boost/assert.hpp> is included, BOOST_ASSERT_MSG(expr) expands to ((void)0) when NDEBUG is defined. Otherwise the behavior is as if BOOST_ENABLE_ASSERT_HANDLER has been defined.

As is the case with <cassert>, <boost/assert.hpp> can be included multiple times in a single translation unit. BOOST_ASSERT_MSG will be redefined each time as specified above.

BOOST_VERIFY

The macro BOOST_VERIFY has the same behavior as BOOST_ASSERT, except that the expression that is passed to BOOST_VERIFY is always evaluated. This is useful when the asserted expression has desirable side effects; it can also help suppress warnings about unused variables when the only use of the variable is inside an assertion.

  • If the macro BOOST_DISABLE_ASSERTS is defined when <boost/assert.hpp> is included, BOOST_VERIFY(expr) expands to ((void)(expr)).

  • If the macro BOOST_ENABLE_ASSERT_HANDLER is defined when <boost/assert.hpp> is included, BOOST_VERIFY(expr) expands to BOOST_ASSERT(expr).

  • Otherwise, BOOST_VERIFY(expr) expands to ((void)(expr)) when NDEBUG is defined, to BOOST_ASSERT(expr) when it’s not.

BOOST_VERIFY_MSG

The macro BOOST_VERIFY_MSG is similar to BOOST_VERIFY, with an additional parameter, an error message.

  • If the macro BOOST_DISABLE_ASSERTS is defined when <boost/assert.hpp> is included, BOOST_VERIFY_MSG(expr,msg) expands to ((void)(expr)).

  • If the macro BOOST_ENABLE_ASSERT_HANDLER is defined when <boost/assert.hpp> is included, BOOST_VERIFY_MSG(expr,msg) expands to BOOST_ASSERT_MSG(expr,msg).

  • Otherwise, BOOST_VERIFY_MSG(expr,msg) expands to ((void)(expr)) when NDEBUG is defined, to BOOST_ASSERT_MSG(expr,msg) when it’s not.

BOOST_ASSERT_IS_VOID

The macro BOOST_ASSERT_IS_VOID is defined when BOOST_ASSERT and BOOST_ASSERT_MSG are expanded to ((void)0). Its purpose is to avoid compiling and potentially running code that is only intended to prepare data to be used in the assertion.

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);
}

  • By default, BOOST_ASSERT_IS_VOID is defined if NDEBUG is defined.

  • If the macro BOOST_DISABLE_ASSERTS is defined, BOOST_ASSERT_IS_VOID is always defined.

  • If the macro BOOST_ENABLE_ASSERT_HANDLER is defined, BOOST_ASSERT_IS_VOID is never defined.

  • If the macro BOOST_ENABLE_ASSERT_DEBUG_HANDLER is defined, then BOOST_ASSERT_IS_VOID is defined when NDEBUG is defined.

Current Function Macro, <boost/current_function.hpp>

BOOST_CURRENT_FUNCTION

The header <boost/current_function.hpp> defines a single macro, BOOST_CURRENT_FUNCTION, similar to the C99 predefined identifier __func__.

BOOST_CURRENT_FUNCTION expands to a string literal containing the (fully qualified, if possible) name of the enclosing function. If there is no enclosing function, the behavior is unspecified.

Some compilers do not provide a way to obtain the name of the current enclosing function. On such compilers, or when the macro BOOST_DISABLE_CURRENT_FUNCTION is defined, BOOST_CURRENT_FUNCTION expands to "(unknown)".

BOOST_DISABLE_CURRENT_FUNCTION addresses a use case in which the programmer wishes to eliminate the string literals produced by BOOST_CURRENT_FUNCTION from the final executable for security reasons.

Source Location Support, <boost/assert/source_location.hpp>

Description

The header <boost/assert/source_location.hpp> defines source_location, a class representing a source location and containing file, line, function and column information. It’s similar to std::source_location from C++20, but only requires C++03.

The macro BOOST_CURRENT_LOCATION creates a source_location object containing information about the current source location.

Synopsis

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 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;
};

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 \
  ::boost::source_location(__FILE__, __LINE__, BOOST_CURRENT_FUNCTION)

source_location

constexpr source_location() noexcept;
Effects:

Constructs a source_location object for which file_name() and function_name() return "(unknown)", and line() and column() return 0.

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

Constructs a source_location object for which file_name() returns file, function_name() returns function, line() returns the line argument and column() returns the column argument.

operator<<

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

Outputs a string representation of loc to os.

Returns:

os.

BOOST_CURRENT_LOCATION

When BOOST_DISABLE_CURRENT_LOCATION is not defined, the definition of BOOST_CURRENT_LOCATION is:

#define BOOST_CURRENT_LOCATION \
  ::boost::source_location(__FILE__, __LINE__, BOOST_CURRENT_FUNCTION)

Otherwise, BOOST_CURRENT_LOCATION is defined as:

#define BOOST_CURRENT_LOCATION ::boost::source_location()

This allows producing executables that contain no identifying information, for security reasons.

Revision History

Changes in 1.73.0

  • Added source_location.

This documentation is