assert/doc/assert.adoc

////
Copyright 2002, 2007, 2014, 2017 Peter Dimov
Copyright 2011 Beman Dawes
Copyright 2015 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
////

#
:toc:

## 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
```
(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.

## 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
```
(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.