...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
BOOST_ASSERT
BOOST_ASSERT_MSG
BOOST_VERIFY
BOOST_VERIFY_MSG
BOOST_ASSERT_IS_VOID
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
(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, 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.
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
(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.
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.
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.
The macro BOOST_ASSERT_IS_VOID
is defined when BOOST_ASSERT
and BOOST_ASSERT_MSG
, are expanded to ((void)0)
.
This macro is useful 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
, then BOOST_ASSERT_IS_VOID
is defined when NDEBUG
is defined.
Copyright © 2002, 2007, 2014 by Peter Dimov. Copyright © 2011 by Beman Dawes. Copyright © 2015 by Ion Gaztanaga. 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.