debug_assert is a simple, C++11, header-only library that provides a very flexible DEBUG_ASSERT() macro. How many times did you write an assertion macro yourself, because assert() is controlled globally and cannot be enabled for certain parts of the program only? This library solves the problem by providing a flexible, modular assertion macro.

• No dependencies. It only requires std::abort() and - unless DEBUG_ASSERT_NO_STDIO is defined - std::fprintf().
• Single, small header file that just needs to be copied into your own project.
• Customizable assertion handling - assertion failure will call a user-defined function, with user-defined arguments.
• Modular - enable or disable assertions for different parts of the same program.
• Support for levels - give levels to your assertion macro and only enable certain levels of assertions.
• Little preprocessor use - just a single assertion macro which is needed to get the stringified expression and source location. Enabling/Disabling is controlled by compile time programming instead of preprocessor conditionals.
• Fast - even though a disabled assertion will still expand to something, there is no overhead with even basic optimizations enabled and very little without optimization (just the code to read __FILE__ and __LINE__). To be precise: It will only evaluate the assertion expression if the assertion is enabled!

The basic usage of the library is like so:

DEBUG_ASSERT(1 + 1 == 2, my_module{}); // basic
DEBUG_ASSERT(1 + 1 == 2, my_module{}, debug_assert::level<2>{}); // with level

Where my_module is a user-defined tag type that will both control the assertion level and the handler code. It looks like this:

struct my_module
: debug_assert::default_handler, // use the default handler
  debug_assert::set_level<-1> // level -1, i.e. all assertions, 0 would mean none, 1 would be level 1, 2 level 2 or lower,...
{};

A module handler must have static function handle() that takes a debug_assert::source_location, the stringified expression and any additional arguments you pass to DEBUG_ASSERT() (besides the debug_assert::level).

See example.cpp for more information and read the blogpost.

For convenience you can also use CMake to setup the include directory and have options that map to the customizable macros. Simple call add_subdirectory(path/to/debug_assert) and then target_link_libraries(my_target PUBLIC debug_assert). It will not actually build something, only setup the flags. Note that it will not enable C++11 support. The options are named like the macros.

Generated by standardese.

#define DEBUG_ASSERT_MARK_UNREACHABLE

#define DEBUG_ASSERT_FORCE_INLINE

#define DEBUG_ASSERT_CUR_SOURCE_LOCATION

#define DEBUG_ASSERT(Expr, ...)

#define DEBUG_UNREACHABLE(...)

namespace debug_assert
{
    struct source_location;

    template <unsigned Level>
    struct level;

    template <unsigned Level>
    struct set_level;

    struct allow_exception;

    struct no_handler;

    struct default_handler;
}

#define DEBUG_ASSERT_CUR_SOURCE_LOCATION

Expands to the current debug_assert::source_location.

#define DEBUG_ASSERT(Expr, ...)

Usage: `DEBUG_ASSERT(<expr>, <handler>, [<level>], [<handler-specific-args>]. Where:

• <expr> - the expression to check for, the expression !<expr> must be well-formed and contextually convertible to bool.
• <handler> - an object of the module specific handler
• <level> (optional, defaults to 1) - the level of the assertion, must be an object of type debug_assert::level<Level>.
• <handler-specific-args> (optional) - any additional arguments that are just forwarded to the handler function.

It will only check the assertion if <level> is less than or equal to Handler::level. A failed assertion will call: Handler::handle(location, expression, args). location is the debug_assert::source_location at the macro expansion, expression is the stringified expression and args are the <handler-specific-args> as-is. If the handler function returns, it will call [std::abort()].

Notes: Define DEBUG_ASSERT_DISABLE to completely disable this macro, it will expand to nothing. This should not be necessary, the regular version is optimized away completely.

#define DEBUG_UNREACHABLE(...)

Marks a branch as unreachable.

Usage: DEBUG_UNREACHABLE(<handler>, [<level>], [<handler-specific-args>]) Where:

• <handler> - an object of the module specific handler
• <level> (optional, defaults to 1) - the level of the assertion, must be an object of type debug_assert::level<Level>.
• <handler-specific-args> (optional) - any additional arguments that are just forwarded to the handler function.

It will only check the assertion if <level> is less than or equal to Handler::level. A failed assertion will call: Handler::handle(location, "", args). and args are the <handler-specific-args> as-is. If the handler function returns, it will call [std::abort()].

Notes: Define DEBUG_ASSERT_DISABLE to completely disable this macro, it will expand to DEBUG_ASSERT_MARK_UNREACHABLE. This should not be necessary, the regular version is optimized away completely.

struct source_location
{
    const char* file_name;

    unsigned line_number;
};

Defines a location in the source code.

Members:

• line_number - < The file name. < The line number.

template <unsigned Level>
struct level
{
};

Tag type to indicate the level of an assertion.

template <unsigned Level>
struct set_level
{
    static const unsigned level = Level;
};

Helper class that sets a certain level. Inherit from it in your module handler.

struct allow_exception
{
    static const bool throwing_exception_is_allowed = true;
};

Helper class that controls whether the handler can throw or not. Inherit from it in your module handler. If the module does not inherit from this class, it is assumed that the handle does not throw.

struct no_handler
{
    template <typename ... Args>
    static void handle(const source_location&, const char*, Args&&...) noexcept;
};

Does not do anything to handle a failed assertion (except calling std::abort()). Inherit from it in your module handler.

template <typename ... Args>
static void handle(const source_location&, const char*, Args&&...) noexcept;

Effects: Does nothing.

Notes: Can take any additional arguments.

struct default_handler
{
    static void handle(const source_location& loc, const char* expression, const char* message = nullptr) noexcept;
};

The default handler that writes a message to stderr. Inherit from it in your module handler.

static void handle(const source_location& loc, const char* expression, const char* message = nullptr) noexcept;

Effects: Prints a message to stderr.

Notes: It can optionally accept an additional message string.

Notes: If DEBUG_ASSERT_NO_STDIO is defined, it will do nothing.

Thanks a lot to @Manu343726, @verri and @pfultz2.