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