1//// 2Copyright 2002, 2007, 2014, 2017 Peter Dimov 3Copyright 2011 Beman Dawes 4Copyright 2015 Ion Gaztañaga 5 6Distributed under the Boost Software License, Version 1.0. 7 8See accompanying file LICENSE_1_0.txt or copy at 9http://www.boost.org/LICENSE_1_0.txt 10//// 11 12[#assertion_macros] 13# Assertion Macros, <boost/assert.hpp> 14:toc: 15:toc-title: 16:idprefix: 17 18## BOOST_ASSERT 19 20The header `<boost/assert.hpp>` defines the macro `BOOST_ASSERT`, 21which is similar to the standard `assert` macro defined in `<cassert>`. 22The macro is intended to be used in both Boost libraries and user 23code. 24 25* By default, `BOOST_ASSERT(expr)` expands to `assert(expr)`. 26 27* If the macro `BOOST_DISABLE_ASSERTS` is defined when `<boost/assert.hpp>` 28 is included, `BOOST_ASSERT(expr)` expands to `((void)0)`, regardless of whether 29 the macro `NDEBUG` is defined. This allows users to selectively disable `BOOST_ASSERT` without 30 affecting the definition of the standard `assert`. 31 32* If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `<boost/assert.hpp>` 33is included, `BOOST_ASSERT(expr)` expands to 34+ 35``` 36(BOOST_LIKELY(!!(expr))? ((void)0): ::boost::assertion_failed(#expr, 37 BOOST_CURRENT_FUNCTION, __FILE__, __LINE__)) 38``` 39+ 40That is, it evaluates `expr` and if it's false, calls 41`::boost::assertion_failed(#expr, <<current_function.adoc#boost_current_function,BOOST_CURRENT_FUNCTION>>, \\__FILE__, \\__LINE__)`. 42This is true regardless of whether `NDEBUG` is defined. 43+ 44`boost::assertion_failed` is declared in `<boost/assert.hpp>` as 45+ 46``` 47namespace boost 48{ 49 void assertion_failed(char const * expr, char const * function, 50 char const * file, long line); 51} 52``` 53+ 54but it is never defined. The user is expected to supply an appropriate definition. 55 56* If the macro `BOOST_ENABLE_ASSERT_DEBUG_HANDLER` is defined when `<boost/assert.hpp>` 57is included, `BOOST_ASSERT(expr)` expands to `((void)0)` when `NDEBUG` is 58defined. Otherwise the behavior is as if `BOOST_ENABLE_ASSERT_HANDLER` has been defined. 59 60As is the case with `<cassert>`, `<boost/assert.hpp>` 61can be included multiple times in a single translation unit. `BOOST_ASSERT` 62will be redefined each time as specified above. 63 64## BOOST_ASSERT_MSG 65 66The macro `BOOST_ASSERT_MSG` is similar to `BOOST_ASSERT`, but it takes an additional argument, 67a character literal, supplying an error message. 68 69* By default, `BOOST_ASSERT_MSG(expr,msg)` expands to `assert\((expr)&&(msg))`. 70 71* If the macro `BOOST_DISABLE_ASSERTS` is defined when `<boost/assert.hpp>` 72is included, `BOOST_ASSERT_MSG(expr,msg)` expands to `((void)0)`, regardless of whether 73the macro `NDEBUG` is defined. 74 75* If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `<boost/assert.hpp>` 76is included, `BOOST_ASSERT_MSG(expr,msg)` expands to 77+ 78``` 79(BOOST_LIKELY(!!(expr))? ((void)0): ::boost::assertion_failed_msg(#expr, 80 msg, BOOST_CURRENT_FUNCTION, __FILE__, __LINE__)) 81``` 82+ 83This is true regardless of whether `NDEBUG` is defined. 84+ 85`boost::assertion_failed_msg` is declared in `<boost/assert.hpp>` as 86+ 87``` 88namespace boost 89{ 90 void assertion_failed_msg(char const * expr, char const * msg, 91 char const * function, char const * file, long line); 92} 93``` 94+ 95but it is never defined. The user is expected to supply an appropriate definition. 96 97* If the macro `BOOST_ENABLE_ASSERT_DEBUG_HANDLER` is defined when `<boost/assert.hpp>` 98is included, `BOOST_ASSERT_MSG(expr)` expands to `((void)0)` when `NDEBUG` is 99defined. Otherwise the behavior is as if `BOOST_ENABLE_ASSERT_HANDLER` has been defined. 100 101As is the case with `<cassert>`, `<boost/assert.hpp>` 102can be included multiple times in a single translation unit. `BOOST_ASSERT_MSG` 103will be redefined each time as specified above. 104 105## BOOST_VERIFY 106 107The macro `BOOST_VERIFY` has the same behavior as `BOOST_ASSERT`, except that 108the expression that is passed to `BOOST_VERIFY` is always 109evaluated. This is useful when the asserted expression has desirable side 110effects; it can also help suppress warnings about unused variables when the 111only use of the variable is inside an assertion. 112 113* If the macro `BOOST_DISABLE_ASSERTS` is defined when `<boost/assert.hpp>` 114 is included, `BOOST_VERIFY(expr)` expands to `\((void)(expr))`. 115 116* If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `<boost/assert.hpp>` 117 is included, `BOOST_VERIFY(expr)` expands to `BOOST_ASSERT(expr)`. 118 119* Otherwise, `BOOST_VERIFY(expr)` expands to `\((void)(expr))` when `NDEBUG` is 120 defined, to `BOOST_ASSERT(expr)` when it's not. 121 122## BOOST_VERIFY_MSG 123 124The macro `BOOST_VERIFY_MSG` is similar to `BOOST_VERIFY`, with an additional parameter, an error message. 125 126* If the macro `BOOST_DISABLE_ASSERTS` is defined when `<boost/assert.hpp>` 127 is included, `BOOST_VERIFY_MSG(expr,msg)` expands to `\((void)(expr))`. 128 129* If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `<boost/assert.hpp>` 130 is included, `BOOST_VERIFY_MSG(expr,msg)` expands to `BOOST_ASSERT_MSG(expr,msg)`. 131 132* Otherwise, `BOOST_VERIFY_MSG(expr,msg)` expands to `\((void)(expr))` when `NDEBUG` is 133 defined, to `BOOST_ASSERT_MSG(expr,msg)` when it's not. 134 135## BOOST_ASSERT_IS_VOID 136 137The macro `BOOST_ASSERT_IS_VOID` is defined when `BOOST_ASSERT` and `BOOST_ASSERT_MSG` are expanded to `((void)0)`. 138Its purpose is to avoid compiling and potentially running code that is only intended to prepare data to be used in the assertion. 139 140``` 141void MyContainer::erase(iterator i) 142{ 143// Some sanity checks, data must be ordered 144#ifndef BOOST_ASSERT_IS_VOID 145 146 if(i != c.begin()) { 147 iterator prev = i; 148 --prev; 149 BOOST_ASSERT(*prev < *i); 150 } 151 else if(i != c.end()) { 152 iterator next = i; 153 ++next; 154 BOOST_ASSERT(*i < *next); 155 } 156 157#endif 158 159 this->erase_impl(i); 160} 161``` 162 163* By default, `BOOST_ASSERT_IS_VOID` is defined if `NDEBUG` is defined. 164* If the macro `BOOST_DISABLE_ASSERTS` is defined, `BOOST_ASSERT_IS_VOID` is always defined. 165* If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined, `BOOST_ASSERT_IS_VOID` is never defined. 166* If the macro `BOOST_ENABLE_ASSERT_DEBUG_HANDLER` is defined, then `BOOST_ASSERT_IS_VOID` is defined when `NDEBUG` is defined. 167