From f5eda28c9fdb02586a68894a6057fbd75664e013 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Mon, 5 Jun 2017 18:20:02 +0300 Subject: [PATCH] Add .adoc files --- doc/assert.adoc | 148 ++++++++++++++++++++++++++++++++++++++ doc/current_function.adoc | 21 ++++++ doc/index.adoc | 16 +++++ 3 files changed, 185 insertions(+) create mode 100644 doc/assert.adoc create mode 100644 doc/current_function.adoc create mode 100644 doc/index.adoc diff --git a/doc/assert.adoc b/doc/assert.adoc new file mode 100644 index 0000000..5c1e4a9 --- /dev/null +++ b/doc/assert.adoc @@ -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 `` defines the macro `BOOST_ASSERT`, +which is similar to the standard `assert` macro defined in ``. +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 `` + 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 `` + 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 `` 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 `` +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 ``, `` +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 `` +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 `` +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 `` 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 `` +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 ``, `` +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 `` + is included, `BOOST_VERIFY(expr)` expands to `((void)(expr))`. + +* If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `` + 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 `` + is included, `BOOST_VERIFY_MSG(expr,msg)` expands to `((void)(expr))`. + +* If the macro `BOOST_ENABLE_ASSERT_HANDLER` is defined when `` + 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. diff --git a/doc/current_function.adoc b/doc/current_function.adoc new file mode 100644 index 0000000..f202316 --- /dev/null +++ b/doc/current_function.adoc @@ -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)"`. diff --git a/doc/index.adoc b/doc/index.adoc new file mode 100644 index 0000000..944083f --- /dev/null +++ b/doc/index.adoc @@ -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[]