feedc0de/boost_assert
1
0
Fork 0
forked from boostorg/assert
Code Pull Requests Activity

Add .adoc files

Browse Source
This commit is contained in:
Peter Dimov
2017-06-05 18:20:02 +03:00
parent 89e5b86c46
commit f5eda28c9f
3 changed files with 185 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
doc/assert.adoc Normal file
View File

@@ -0,0 +1,148 @@
////
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.

21
doc/current_function.adoc Normal file
View File

@@ -0,0 +1,21 @@
////
Copyright 2002, 2017 Peter Dimov
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
////
## BOOST_CURRENT_FUNCTION
The header `boost/current_function.hpp` defines a single macro, `BOOST_CURRENT_FUNCTION`,
similar to the C99 predefined identifier `__func__`.
`BOOST_CURRENT_FUNCTION` expands to a string literal containing
the (fully qualified, if possible) name of the enclosing function. If there is
no enclosing function, the behavior is unspecified.
Some compilers do not provide a way to obtain the name of the current enclosing
function. On such compilers, `BOOST_CURRENT_FUNCTION` expands to
`"(unknown)"`.

16
doc/index.adoc Normal file
View File

@@ -0,0 +1,16 @@
////
Copyright 2017 Peter Dimov
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
////
# Boost.Assert
The Boost.Assert library...
include::assert.adoc[]
include::current_function.adoc[]