//// Copyright 2002, 2007, 2014, 2017 Peter Dimov Copyright 2011 Beman Dawes Copyright 2015 Ion Gaztañaga 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 //// [#assertion_macros] # Assertion Macros, :toc: :toc-title: :idprefix: ## BOOST_ASSERT The header `` defines the macro `BOOST_ASSERT`, which is similar to the standard `assert` macro defined in ``. 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 `` 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 `` 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, <>, \\__FILE__, \\__LINE__)`. This is true regardless of whether `NDEBUG` is defined. + `boost::assertion_failed` is declared in `` 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 `` 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 ``, `` 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 `` 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 `` 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 `` 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 `` 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 ``, `` 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 `` is included, `BOOST_VERIFY(expr)` expands to `\((void)(expr))`. * If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `` 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 `` is included, `BOOST_VERIFY_MSG(expr,msg)` expands to `\((void)(expr))`. * If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `` 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.