]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>Boost: assert.hpp documentation</title> | |
5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> | |
6 | </head> | |
7 | <body bgcolor="white" style="MARGIN-LEFT: 5%; MARGIN-RIGHT: 5%"> | |
8 | <table border="0" width="100%"> | |
9 | <tr> | |
10 | <td width="277"><a href="../../index.htm"> <img src="../../boost.png" alt="boost.png (6897 bytes)" width="277" height="86" border="0" /></a> | |
11 | </td> | |
12 | <td align="center"> | |
13 | <h1>assert.hpp</h1> | |
14 | </td> | |
15 | </tr> | |
16 | <tr> | |
17 | <td colspan="2" height="64"> </td> | |
18 | </tr> | |
19 | </table> | |
20 | <p> | |
21 | <a href="#BOOST_ASSERT">BOOST_ASSERT</a><br /> | |
22 | <a href="#BOOST_ASSERT_MSG">BOOST_ASSERT_MSG</a><br /> | |
23 | <a href="#BOOST_VERIFY">BOOST_VERIFY</a><br /> | |
24 | <a href="#BOOST_VERIFY_MSG">BOOST_VERIFY_MSG</a><br /> | |
25 | <a href="#BOOST_ASSERT_IS_VOID">BOOST_ASSERT_IS_VOID</a><br /> | |
26 | </p> | |
27 | ||
28 | <h2><a name="BOOST_ASSERT">BOOST_ASSERT</a></h2> | |
29 | <p> | |
30 | The header <code><boost/assert.hpp></code> defines the macro <code>BOOST_ASSERT</code>, | |
31 | which is similar to the standard <code>assert</code> macro defined in <code><cassert></code>. | |
32 | The macro is intended to be used in both Boost libraries and user | |
33 | code. | |
34 | </p> | |
35 | <p>• By default, <code>BOOST_ASSERT(expr)</code> expands to <code>assert(expr)</code>.</p> | |
36 | <p>• If the macro <code>BOOST_DISABLE_ASSERTS</code> is defined when <code><boost/assert.hpp></code> | |
37 | is included, <code>BOOST_ASSERT(expr)</code> expands to <code>((void)0)</code>, regardless of whether | |
38 | the macro <code>NDEBUG</code> is defined. This allows users to selectively disable <code>BOOST_ASSERT</code> without | |
39 | affecting the definition of the standard <code>assert</code>.</p> | |
40 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_HANDLER</code> is defined when <code><boost/assert.hpp></code> | |
41 | is included, <code>BOOST_ASSERT(expr)</code> expands to</p> | |
42 | <blockquote> | |
43 | <pre>(<a href="../config/doc/html/boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_helper_macros">BOOST_LIKELY</a>(!!(expr))? ((void)0): ::boost::assertion_failed(#expr, <a href="current_function.html">BOOST_CURRENT_FUNCTION</a>, __FILE__, __LINE__))</pre> | |
44 | </blockquote> | |
45 | <p>That is, it evaluates <code>expr</code> and if it's false, calls <code>::boost::assertion_failed(#expr, BOOST_CURRENT_FUNCTION, __FILE__, __LINE__)</code>. | |
46 | This is true regardless of whether <code>NDEBUG</code> is defined.</p> | |
47 | <p><code>boost::assertion_failed</code> is declared in <code><boost/assert.hpp></code> as</p> | |
48 | <blockquote> | |
49 | <pre>namespace boost | |
50 | { | |
51 | void assertion_failed(char const * expr, char const * function, char const * file, long line); | |
52 | } | |
53 | </pre> | |
54 | </blockquote> | |
55 | <p>but it is never defined. The user is expected to supply an appropriate | |
56 | definition.</p> | |
57 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_DEBUG_HANDLER</code> is defined when <code><boost/assert.hpp></code> | |
58 | is included, <code>BOOST_ASSERT(expr)</code> expands to <code>((void)0)</code> when <code>NDEBUG</code> is | |
59 | defined. Otherwise the behavior is as if <code>BOOST_ENABLE_ASSERT_HANDLER</code> has been defined.</p> | |
60 | <p>As is the case with <code><cassert></code>, <code><boost/assert.hpp></code> | |
61 | can be included multiple times in a single translation unit. <code>BOOST_ASSERT</code> | |
62 | will be redefined each time as specified above.</p> | |
63 | ||
64 | <h2><a name="BOOST_ASSERT_MSG">BOOST_ASSERT_MSG</a></h2> | |
65 | <p> | |
66 | The macro <code>BOOST_ASSERT_MSG</code> is similar to <code>BOOST_ASSERT</code>, but it takes an additional argument, | |
67 | a character literal, supplying an error message.</p> | |
68 | <p>• By default, <code>BOOST_ASSERT_MSG(expr,msg)</code> expands to <code>assert((expr)&&(msg))</code>.</p> | |
69 | <p>• If the macro <code>BOOST_DISABLE_ASSERTS</code> is defined when <code><boost/assert.hpp></code> | |
70 | is included, <code>BOOST_ASSERT_MSG(expr,msg)</code> expands to <code>((void)0)</code>, regardless of whether | |
71 | the macro <code>NDEBUG</code> is defined.</p> | |
72 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_HANDLER</code> is defined when <code><boost/assert.hpp></code> | |
73 | is included, <code>BOOST_ASSERT_MSG(expr,msg)</code> expands to</p> | |
74 | <blockquote> | |
75 | <pre>(<a href="../config/doc/html/boost_config/boost_macro_reference.html#boost_config.boost_macro_reference.boost_helper_macros">BOOST_LIKELY</a>(!!(expr))? ((void)0): ::boost::assertion_failed_msg(#expr, msg, <a href="current_function.html">BOOST_CURRENT_FUNCTION</a>, __FILE__, __LINE__))</pre> | |
76 | </blockquote> | |
77 | <p>This is true regardless of whether <code>NDEBUG</code> is defined.</p> | |
78 | <p><code>boost::assertion_failed_msg</code> is declared in <code><boost/assert.hpp></code> as</p> | |
79 | <blockquote> | |
80 | <pre>namespace boost | |
81 | { | |
82 | void assertion_failed_msg(char const * expr, char const * msg, char const * function, char const * file, long line); | |
83 | } | |
84 | </pre> | |
85 | </blockquote> | |
86 | <p>but it is never defined. The user is expected to supply an appropriate | |
87 | definition.</p> | |
88 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_DEBUG_HANDLER</code> is defined when <code><boost/assert.hpp></code> | |
89 | is included, <code>BOOST_ASSERT_MSG(expr)</code> expands to <code>((void)0)</code> when <code>NDEBUG</code> is | |
90 | defined. Otherwise the behavior is as if <code>BOOST_ENABLE_ASSERT_HANDLER</code> has been defined.</p> | |
91 | <p>As is the case with <code><cassert></code>, <code><boost/assert.hpp></code> | |
92 | can be included multiple times in a single translation unit. <code>BOOST_ASSERT_MSG</code> | |
93 | will be redefined each time as specified above.</p> | |
94 | ||
95 | <h2><a name="BOOST_VERIFY">BOOST_VERIFY</a></h2> | |
96 | <p>The macro <code>BOOST_VERIFY</code> has the same behavior as <code>BOOST_ASSERT</code>, except that | |
97 | the expression that is passed to <code>BOOST_VERIFY</code> is always | |
98 | evaluated. This is useful when the asserted expression has desirable side | |
99 | effects; it can also help suppress warnings about unused variables when the | |
100 | only use of the variable is inside an assertion.</p> | |
101 | <p>• If the macro <code>BOOST_DISABLE_ASSERTS</code> is defined when <code><boost/assert.hpp></code> | |
102 | is included, <code>BOOST_VERIFY(expr)</code> expands to <code>((void)(expr))</code>.</p> | |
103 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_HANDLER</code> is defined when <code><boost/assert.hpp></code> | |
104 | is included, <code>BOOST_VERIFY(expr)</code> expands to <code>BOOST_ASSERT(expr)</code>.</p> | |
105 | <p>• Otherwise, <code>BOOST_VERIFY(expr)</code> expands to <code>((void)(expr))</code> when <code>NDEBUG</code> is | |
106 | defined, to <code>BOOST_ASSERT(expr)</code> when it's not.</p> | |
107 | <h2><a name="BOOST_VERIFY_MSG">BOOST_VERIFY_MSG</a></h2> | |
108 | <p>The macro <code>BOOST_VERIFY_MSG</code> is similar to <code>BOOST_VERIFY</code>, with an additional parameter, an error message.</p> | |
109 | <p>• If the macro <code>BOOST_DISABLE_ASSERTS</code> is defined when <code><boost/assert.hpp></code> | |
110 | is included, <code>BOOST_VERIFY_MSG(expr,msg)</code> expands to <code>((void)(expr))</code>.</p> | |
111 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_HANDLER</code> is defined when <code><boost/assert.hpp></code> | |
112 | is included, <code>BOOST_VERIFY_MSG(expr,msg)</code> expands to <code>BOOST_ASSERT_MSG(expr,msg)</code>.</p> | |
113 | <p>• Otherwise, <code>BOOST_VERIFY_MSG(expr,msg)</code> expands to <code>((void)(expr))</code> when <code>NDEBUG</code> is | |
114 | defined, to <code>BOOST_ASSERT_MSG(expr,msg)</code> when it's not.</p> | |
115 | <hr /> | |
116 | <p> | |
117 | <h2><a name="BOOST_ASSERT_IS_VOID">BOOST_ASSERT_IS_VOID</a></h2> | |
118 | <p>The macro <code>BOOST_ASSERT_IS_VOID</code> is defined when <code>BOOST_ASSERT</code> and <code>BOOST_ASSERT_MSG</code>, are expanded to <code>((void)0)</code>. | |
119 | This macro is useful to avoid compiling and potentially running code that is only intended to prepare data to be used in the assertion.</p> | |
120 | <blockquote> | |
121 | <pre> | |
122 | void MyContainer::erase(iterator i) | |
123 | { | |
124 | //Some sanity checks, data must be ordered | |
125 | #ifndef BOOST_ASSERT_IS_VOID | |
126 | if(i != c.begin()){ | |
127 | iterator prev = i; | |
128 | --prev; | |
129 | BOOST_ASSERT(*prev < *i); | |
130 | } | |
131 | else if(i != c.end()){ | |
132 | iterator next = i; | |
133 | ++next; | |
134 | BOOST_ASSERT(*i < *next); | |
135 | } | |
136 | #endif | |
137 | this->erase_impl(i); | |
138 | } | |
139 | </pre> | |
140 | </blockquote> | |
141 | ||
142 | ||
143 | <p>• By default, <code>BOOST_ASSERT_IS_VOID</code> is defined if <code>NDEBUG</code> is defined.</p> | |
144 | <p>• If the macro <code>BOOST_DISABLE_ASSERTS</code> is defined <code>BOOST_ASSERT_IS_VOID</code> is always defined.</p> | |
145 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_HANDLER</code> is defined <code>BOOST_ASSERT_IS_VOID</code> is never defined.</p> | |
146 | <p>• If the macro <code>BOOST_ENABLE_ASSERT_DEBUG_HANDLER</code>, then <code>BOOST_ASSERT_IS_VOID</code> is defined when <code>NDEBUG</code> is defined.</p> | |
147 | <hr /> | |
148 | <p> | |
149 |