1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
////
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, <boost/assert.hpp>
:toc:
:toc-title:
:idprefix:
## 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
+
```none
(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, <<current_function.adoc#boost_current_function,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
+
```none
(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.
## 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.
|
