KASSERT Documentation Overview

Functionallity

• Assertions :
  • simple assert (KASSERT),
  • throwing assert (THROWING_KASSERT), and
  • a trowing assert with custom exception (THROWING_KASSERT_SPECIFIED)
• Assertion levels : simple configuration of different assertion levels
• Expression Expansions : easy extensibility for custom data types in error messages

Example

The KASSERT macros accepts 1, 2 or 3 arguments.

KASSERT(1 + 1 == 3, "The world is a lie!", kassert::assert::normal);
KASSERT(1 + 1 == 3, "The world is a lie!"); // use default assertion level (kassert::assert::normal)
KASSERT(1 + 1 == 3); // omit custom error message

You can also use C++ streams to build custom error messages on the fly.

int a = 1;
int b = 3;
KASSERT(a + a == b, "Under the assumption that a is " << a << ", the world is a lie!");

Use THROWING_KASSERT to throw an exception if the assertion fails. This requires the target property KASSERT_EXCEPTION_MODE to be set to ON on the target linking against kassert. If exception mode is not enabled, THROWING_KASSERT acts the same as KASSERT.

THROWING_KASSERT(1 + 1 == 3, "The world is a lie!");
THROWING_KASSERT(1 + 1 == 3); // omit custom error message

You can also throw a custom exception type using the THROWING_KASSERT_SPECIFIED macro:

THROWING_KASSERT_SPECIFIED(1 + 1 == 3, "The world is a lie!", your::ns::Exception [, ...]);

The constructor of your custom exception type must be called with a std::string as its first argument, followed by the remaining arguments [, ...] passed to THROWING_KASSERT_SPECIFIED.

Assertion Levels

Assertions are enabled if their assertion level (optional third parameter of KASSERT) is less than or equal to the active assertion level. The default level is kassert::assert::normal (30). Set the CMake target property KASSERT_ASSERTION_LEVEL on you target linking against kassert to the numeric value of the desired assertion level. If omitted, the assertion level is set to 0, which disables all assertions.

add_library(my_code ...)
target_link_libraries(my_code PRIVATE kassert::kassert)
set_target_properties(my_code PROPERTIES KASSERT_ASSERTION_LEVEL 10)

Custom Assertion Levels

You are free to define your own assertion levels. For instance:

namespace kamping::assert {
#define KAMPING_ASSERTION_LEVEL_LIGHT 20
constexpr int light = KAMPING_ASSERTION_LEVEL_LIGHT;
 
#define KAMPING_ASSERTION_LEVEL_HEAVY 40
constexpr int heavy = KAMPING_ASSERTION_LEVEL_HEAVY;
} // namespace kamping::assert 

Requirements

• C++17-ready compiler (GCC, Clang, ICX)
• Building this documentation requires Doxygen 1.9.2 or newer

Vendoring Support

KAssert can be embedded in other libraries with custom namespaces and macro names to prevent naming conflicts.

When to vendor:** Use vendoring when developing a library that uses KAssert internally to avoid conflicts with user code that might also use KAssert.

Configuration Variables

• KASSERT_VENDOR_ID - Base identifier for deriving other variables
• KASSERT_CMAKE_NAMESPACE - Prefix for all CMake targets
• KASSERT_CXX_NAMESPACE - C++ namespace for the library
• KASSERT_INCLUDE_SUBDIR - Subdirectory for header installation
• KASSERT_PREFIX - The prefix for all macros

Example

set(KASSERT_VENDOR_ID "myassert")
add_subdirectory(vendor/kassert)

This generates macros like MYASSERT() instead of KASSERT().

LICENSE

KAssert is released under the MIT License. See ./LICENSE for details.