Boost: assert.hpp documentation

| # assert.hpp

BOOST_ASSERT
BOOST_ASSERT_MSG
BOOST_VERIFY
BOOST_VERIFY_MSG

## 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.

Copyright © 2002, 2007, 2014 by Peter Dimov. Copyright © 2011 by Beman Dawes. Distributed under the Boost Software License, Version 1.0. See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt.