Boost: assert.hpp documentation

| # assert.hpp

BOOST_ASSERT
BOOST_ASSERT_MSG
BOOST_VERIFY

## 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)` is equivalent to `assert(expr)`.

If the macro BOOST_DISABLE_ASSERTS is defined when <boost/assert.hpp> is included, `BOOST_ASSERT(expr)` is defined as `((void)0)`. 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)` evaluates expr and, if the result is false, evaluates the expression

> `::boost::assertion_failed(#expr, BOOST_CURRENT_FUNCTION, __FILE__, __LINE__)`

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.

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 header <boost/assert.hpp> defines the macro BOOST_ASSERT_MSG, which is similar to the standard assert macro defined in <cassert>, but with an additional macro parameter supplying an error message. The macro is intended to be used in both Boost libraries and user code.

`BOOST_ASSERT_MSG(expr, msg)` is equivalent to `((void)0)` if BOOST_DISABLE_ASSERTS or NDEBUG are defined or `expr` evaluates to `true`. If those macros and BOOST_ENABLE_ASSERT_HANDLER are not defined, and `expr` evaluates to `false`, an error message that includes `#expr`, `msg`, `BOOST_CURRENT_FUNCTION`, `__FILE__`, and `__LINE__` is sent to output stream BOOST_ASSERT_MSG_OSTREAM and `std::abort()` is called.

BOOST_ASSERT_MSG_OSTREAM defines the output stream. It defaults to `std::cerr`. Integrated development environments (IDE's) like Microsoft Visual Studio may produce easier to understand output if messages go to a different stream, such as `std::cout`. Users may define BOOST_ASSERT_MSG_OSTREAM before including <boost/assert.hpp> to specify a different output stream.

If the macro BOOST_ENABLE_ASSERT_HANDLER is defined when <boost/assert.hpp> is included, instead of sending a error message to an output stream, this expression is evaluated

> `::boost::assertion_failed_msg(#expr, msg, BOOST_CURRENT_FUNCTION, __FILE__, __LINE__)`

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.

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

<boost/assert.hpp> also defines the macro BOOST_VERIFY. It has exactly 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.

Copyright © 2002, 2007 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.