Reference

Namespaces

breezeThe library's top-level namespace.

Defines

Defines (dump_expression.hpp)

BREEZE_DUMP_EXPRESSION(expression)

Displays an expression and its value to std::cout.

A simple macro for quickly dumping a variable or, generally, an expression to std::cout.

It was born as "DUMP_VARIABLE" but then I immediately found a usage where I wanted to display something like i + j, so I renamed it to "DUMP_EXPRESSION".

It's intended that you use this just for quick and dirty checks, and that you remove it after that.

The expression is shown in the form
<expression
> = value
. If expression contains macro invocations, the macros are expanded, but the unexpanded form is displayed, too. In any case, the output ends with std::endl.

Note
The
#include
's are not part of the interface.

Defines (assert.hpp)

BREEZE_ASSERT(expression)

Asserts that a condition is true.

BREEZE_ASSERT() is a simple runtime assertion facility. Differently from the standard assert(), it has always the same expansion (regardless of NDEBUG).

The code BREEZE_ASSERT( expr ) expands to an expression, let's call it assert_expr, which contains expr as a sub-expression.

expr must have type bool or cv-qualified bool (this is a change from the past: we used to accept anything implicitly or explicitly convertible to bool; which means that e.g. expr could be the name of a std::optional—we think the new specification is safer).

When assert_expr is evaluated: if expr is false, an assertion is triggered; if it is true, the evaluation of assert_expr has no effects besides the evaluation of the sub-expression expr.

In this context, "triggering an assertion" means calling the current assert handler (see set_assert_handler()), passing it information related to the specific BREEZE_ASSERT() invocation (in particular, the text of the expression, the source file name and the line number).

Rationale
It has become common practice to define the macro NDEBUG when compiling the "release" versions of a product. Many IDEs do so silently. In fact, NDEBUG (or a logical complement of it, such as _DEBUG) has become the macro which is usually checked for by your library code to know which version of it (release/debug) you want to link with.

We believe, though, that assertions must be left on in the release builds. So we wanted an assert macro decoupled from NDEBUG. (Thinking of it, there has been a fatal misunderstanding: the C committee thought of a macro to enable/disable assertions, but alas named it "NDEBUG", which suggests "no debug". And that's the meaning everyone seems to have assigned to it. Had they called it e.g. "NASSERT" all this wouldn't probably have happened.)

About the possibility to throw an exception instead of terminating the program: while critical software will certainly need to terminate immediately in case of a programming error, there are applications which can continue: consider e.g. an editor, which could give the user a chance to save their work before aborting.

Mentioned in:

Basic info / Supported compilers

Defines (paste.hpp)

BREEZE_PASTE(x,y)
x ## y

Concatenates two preprocessing tokens.

Concatenates the two preprocessing tokens which end the argument x and start the argument y, respectively, by using the ## operator.

Naming rationale
Though both the C and the C++ standard use the term "concatenate", and not "paste", with reference to what ## does, we preferred the shorter word, especially considering that this macro is often invoked within other macro invocations. "Token pasting" is a well-established expression within the C and C++ communities. (A similar comment applies, obviously, to the _AFTER_EXPANSION variant, which has an even longer name.)

Also, the names "TOKEN_PASTE" and "PASTE_TOKENS" were rejected as, respectively, not verb-based and using plural (which would have been inconsistent in our library).

See
BREEZE_PASTE_AFTER_EXPANSION().

Defines (paste_after_expansion.hpp)

BREEZE_PASTE_AFTER_EXPANSION(x,y)
BREEZE_PASTE( x, y )

Concatenates two preprocessing tokens after macro expansion.

Applies BREEZE_PASTE() to the result of performing macro replacement on the arguments x and y.

See BREEZE_PASTE() for the naming rationale.

Defines (prevent_macro_expansion.hpp)

BREEZE_PREVENT_MACRO_EXPANSION

Prevents the expansion of a function-like macro.

The only purpose of this macro is to prevent the expansion of the preceding identifier, in case it is defined as a function-like macro. Any macro would do (in fact, anything which isn't an open paren), but this has a self-documenting name.

Typically used for the identifiers min and max. Example:

``` int const m = std::numeric_limits< int >::max BREEZE_PREVENT_MACRO_EXPANSION () ; ```

Note that you can prevent macro substitution by enclosing the offending name in parentheses, but that also inhibits ADL, whereas this macro has absolutely no effect in that regard.

Defines (stringize.hpp)

BREEZE_STRINGIZE(x)
# x

Stringizes preprocessing tokens.

Expands to a string literal obtained with # x.

See
BREEZE_STRINGIZE_AFTER_EXPANSION().

Defines (stringize_after_expansion.hpp)

BREEZE_STRINGIZE_AFTER_EXPANSION(x)
BREEZE_STRINGIZE( x )

Stringizes preprocessing tokens after macro expansion.

Stringizes (with BREEZE_STRINGIZE()) the result of performing macro replacement on the argument x.

Defines (to_string.tpp)

BREEZE_print_period(period,literal)
template<>
inline void
print_period< period >( std::ostringstream & dest )
{
dest << literal ;
}