Public API

BREEZE_DUMP_EXPRESSION(expression)

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.

BREEZE_ASSERT(expression)

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

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:

Getting Started / Supported compilers

BREEZE_PASTE(x,y)
x ## y

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

Naming rationale

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().

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

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

See BREEZE_PASTE() for the naming rationale.

BREEZE_PREVENT_MACRO_EXPANSION

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.

BREEZE_STRINGIZE(x)
# x

Expands to a string literal obtained with # x.

See

BREEZE_STRINGIZE_AFTER_EXPANSION().

BREEZE_STRINGIZE_AFTER_EXPANSION(x)
BREEZE_STRINGIZE( x )

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