Corrade/Utility/Assert.h file

#define CORRADE_NO_ASSERT

Disable all assertions.

This macro is not defined by Corrade, but rather meant to be defined by the user. When defined, assertions are not checked at all. See documentation of CORRADE_ASSERT(), CORRADE_CONSTEXPR_ASSERT(), CORRADE_ASSERT_OUTPUT(), CORRADE_ASSERT_UNREACHABLE(), CORRADE_INTERNAL_ASSERT(), CORRADE_INTERNAL_CONSTEXPR_ASSERT(), CORRADE_INTERNAL_ASSERT_OUTPUT(), CORRADE_INTERNAL_ASSERT_EXPRESSION() and CORRADE_INTERNAL_ASSERT_UNREACHABLE() for detailed description of given macro behavior.

#define CORRADE_GRACEFUL_ASSERT

Gracefully print assertions.

This macro is not defined by Corrade, but rather meant to be defined by the user. Unlike CORRADE_NO_ASSERT and in case the error output is redirected (i.e., in a test verifying the assert behavior) this macro checks assertions and prints a message on error, but calls return instead of aborting.

See documentation of CORRADE_ASSERT(), CORRADE_CONSTEXPR_ASSERT(), CORRADE_ASSERT_OUTPUT() and CORRADE_ASSERT_UNREACHABLE() for detailed description of given macro behavior. The CORRADE_INTERNAL_ASSERT(), CORRADE_INTERNAL_CONSTEXPR_ASSERT(), CORRADE_INTERNAL_ASSERT_OUTPUT(), CORRADE_INTERNAL_ASSERT_EXPRESSION() and CORRADE_INTERNAL_ASSERT_UNREACHABLE() are meant to check internal conditions and thus are not affected by this macro.

When both CORRADE_NO_ASSERT and CORRADE_GRACEFUL_ASSERT are defined, CORRADE_NO_ASSERT has a precedence. When both CORRADE_STANDARD_ASSERT and CORRADE_GRACEFUL_ASSERT are defined, CORRADE_STANDARD_ASSERT has a precedence — i.e., the assertions aren't graceful in that case. This precedence is reflected also in the CORRADE_SKIP_IF_NO_ASSERT() helper in the TestSuite library

#define CORRADE_STANDARD_ASSERT

Use standard assert.

This macro is not defined by Corrade, but rather meant to be defined by the user. This macro causes all CORRADE_ASSERT(), CORRADE_CONSTEXPR_ASSERT(), CORRADE_ASSERT_OUTPUT(), CORRADE_ASSERT_UNREACHABLE(), CORRADE_INTERNAL_ASSERT(), CORRADE_INTERNAL_CONSTEXPR_ASSERT(), CORRADE_INTERNAL_ASSERT_OUTPUT(), CORRADE_INTERNAL_ASSERT_EXPRESSION() and CORRADE_INTERNAL_ASSERT_UNREACHABLE() to be only wrappers around the standard assert(), using just the expression and discarding the message, if any. This makes them more lightweight, since Corrade::Utility::Debug does not need to be pulled in, on the other hand only the failed expression is printed to the output without any human-readable description. See documentation of a particular assert macro for more information.

When this macro is defined, CORRADE_NO_ASSERT and the standard NDEBUG macro have the same effect.

#define CORRADE_ASSERT_INCLUDE new in Git master

Assertion include.

This macro is not defined by Corrade, but rather meant to be defined by the user. If defined, it's used as #include CORRADE_ASSERT_INCLUDE at the top of this file and its value has to include the enclosing <> or "" characters as well. The file can then contain overrides for either the CORRADE_ASSERT_ABORT() and CORRADE_ASSERT_MESSAGE_ABORT() macros that affect all asserts or modify just individual macros one by one. The desired use case is to pass it via compiler flags to override the assert behavior for the whole project, for example with -DCORRADE_ASSERT_INCLUDE="<assertOverrides.h>" or -DCORRADE_ASSERT_INCLUDE="\"assertOverrides.h\"". Note that different toolchains and buildsystems may need various workarounds to pass the angle brackets or inner quotes through.

If you need to also link a certain library in addition to the include, specify it among linker flags. In case of CMake for example, while adding this define meant editing CMAKE_CXX_FLAGS, specifying the library to link to means modifying the CMAKE_SHARED_LINKER_FLAGS and/or CMAKE_EXE_LINKER_FLAGS variables.

#define CORRADE_ASSERT_ABORT() new in Git master

Assertion abort implementation.

Used by all Corrade assertion macros if CORRADE_STANDARD_ASSERT is not defined, calls std::abort() by default. If CORRADE_STANDARD_ASSERT is defined, this macro isn't used as standard assert() is called instead.

You can override this implementation by placing your own #define CORRADE_ASSERT_ABORT() before including the Corrade/Utility/Assert.h header. The macro value is expected to be a single expression without a trailing semicolon and the called function being marked as [[noreturn]], otherwise any use of CORRADE_ASSERT_UNREACHABLE() and similar macros may result in the compiler complaining that not all code paths return a value. Also note that if this macro is overriden, the header doesn't #include <cstdlib> for std::abort() anymore, you have to do that yourself if needed. See also CORRADE_ASSERT_MESSAGE_ABORT() for a way to override both the message printing and the abort.

Example usage, assuming the abortWithBacktrace() function is defined somewhere else:

[[noreturn]] void abortWithBacktrace();

#define CORRADE_ASSERT_ABORT() abortWithBacktrace()

#include <Corrade/Utility/Assert.h>

Alternatively you can put the #define CORRADE_ASSERT_ABORT() macro into a dedicated header file and pass e.g. -DCORRADE_ASSERT_INCLUDE="\"abortWithBacktrace.h\"" in compiler flags to override the abort behavior for the whole project. See CORRADE_ASSERT_INCLUDE for more information.

#define CORRADE_ASSERT_MESSAGE_ABORT(...) new in Git master

Assertion message and abort implementation.

Used by all Corrade assertion macros if neither CORRADE_STANDARD_ASSERT nor CORRADE_GRACEFUL_ASSERT is defined. If CORRADE_STANDARD_ASSERT is defined, this macro isn't used as standard assert() is called instead, if CORRADE_GRACEFUL_ASSERT is defined, the message printing cannot be overriden, only abort behavior.

You can override this implementation by placing your own #define CORRADE_ASSERT_MESSAGE_ABORT(...) before including the Corrade/Utility/Assert.h header. The macro value is expected to be a sequence of expressions each with a trailing semicolon. Note that if this macro is overriden, the header doesn't #include <Corrade/Utility/Debug.h> for Utility::Debug anymore, you have to do that yourself if needed. You can also override just CORRADE_ASSERT_ABORT() if you only need to control the abort behavior but not message printing.

Example usage, assuming the logAndReportAssertion() function is defined somewhere else. The override formats the message to a string, passes it to this function but still also prints it to Utility::Error to have it shown in the standard error output as well, and delegates to CORRADE_ASSERT_ABORT() at the end. You can do any abort-like operation instead of calling that macro, but in that case it's recommended to override the CORRADE_ASSERT_ABORT() implementation directly, as it will affect all such cases in that case, not just aborts with messages.

void logAndReportAssertion(const char* message);

#define CORRADE_ASSERT_MESSAGE_ABORT(...)                                   \
    Corrade::Containers::String out;                                        \
    Corrade::Utility::Error{&out, Corrade::Utility::Error::Flag::NoNewlineAtTheEnd} \
        << __VA_ARGS__;                                                     \
    logAndReportAssertion(out.data());                                      \
    Corrade::Utility::Error{Corrade::Utility::Error::defaultOutput()} << out; \
    CORRADE_ASSERT_ABORT();

#include <Corrade/Utility/Assert.h>

Alternatively you can put the #define CORRADE_ASSERT_MESSAGE_ABORT(...) macro into a dedicated header file and pass e.g. -DCORRADE_ASSERT_INCLUDE="\"logAndReportAssertion.h\"" in compiler flags to override the abort behavior for the whole project. See CORRADE_ASSERT_INCLUDE for more information.

#define CORRADE_ASSERT(condition, message, returnValue)

Assertion macro.

Usable for sanity checks on user input, as it prints explanational message on error.

By default, if assertion fails, message is printed to error output and the application aborts. If CORRADE_GRACEFUL_ASSERT is defined and Corrade::Utility::Error output is redirected (i.e., in tests verifying the assert behavior), the message is printed and the function returns with returnValue instead of aborting. If CORRADE_STANDARD_ASSERT is defined, this macro expands to assert(condition), ignoring message. If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro expands to do {} while(false). Example usage:

T operator[](std::size_t pos) const {
    CORRADE_ASSERT(pos < size(), "Array::operator[](): index out of range", {});
    return data[pos];
}

If the function has return type void, just use an empty parameter (allowed in C++11):

void compile() {
    CORRADE_ASSERT(!sources.isEmpty(), "Shader::compile(): no sources added", );

    // ...
}

You can use stream output operators for formatting just like when printing to Corrade::Utility::Debug output:

CORRADE_ASSERT(pos < size(), "Array::operator[](): accessing element"
    << pos << "in an array of size" << size(), {});

You can override this implementation by placing your own #define CORRADE_ASSERT before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.

#define CORRADE_CONSTEXPR_ASSERT(condition, message)

Constexpr assertion macro.

Unlike CORRADE_ASSERT() this macro can be used in C++11 constexpr functions like this:

constexpr int divide(int a, int b) {
    return CORRADE_CONSTEXPR_ASSERT(b, "divide(): can't divide by zero"), a/b;
}

In a constexpr context, if assertion fails, the code fails to compile. In a non- constexpr context, if assertion fails, message is printed to error output and the application aborts. If CORRADE_GRACEFUL_ASSERT is defined and Corrade::Utility::Error output is redirected (i.e., in tests verifying the assert behavior), the message is printed and the rest of the function gets executed as usual instead of aborting. If CORRADE_STANDARD_ASSERT is defined, message is ignored and the standard assert() is called if condition fails. If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro expands to static_cast<void>(0).

As with CORRADE_ASSERT(), you can use stream output operators for formatting just like when printing to Corrade::Utility::Debug output.

The implementation is based on the Asserts in constexpr functions article by Andrzej Krzemieński and the followup discussion.

You can override this implementation by placing your own #define CORRADE_CONSTEXPR_ASSERT before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.

#define CORRADE_ASSERT_OUTPUT(call, message, returnValue)

Call output assertion macro.

Unlike CORRADE_ASSERT(), this macro performs the call even if CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), making it usable for checking function output. Otherwise the behavior is the same as with CORRADE_ASSERT(). Example usage:

CORRADE_ASSERT_OUTPUT(initialize(userParam),
    "Initialization failed: wrong parameter" << userParam, );

You can override this implementation by placing your own #define CORRADE_ASSERT_OUTPUT before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.

#define CORRADE_ASSERT_UNREACHABLE(message, returnValue)

Assert that the code is unreachable.

By default, if code marked with this macro is reached, message is printed to error output and the application aborts. If CORRADE_GRACEFUL_ASSERT is defined and Corrade::Utility::Error output is redirected (i.e., in tests verifying the assert behavior), the message is printed and the function returns with returnValue instead of aborting. If CORRADE_STANDARD_ASSERT is defined, this macro expands to assert(!"unreachable code"). If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro hints to the compiler that given code is not reachable, possibly helping the optimizer (using a compiler builtin on GCC, Clang and MSVC; calling CORRADE_ASSERT_ABORT(), which is std::abort() by default, otherwise). A return statement can thus be safely omitted in a code path following this macro without causing any compiler warnings or errors. Example usage:

std::string statusString(Status status) {
    switch(status) {
        case Status::Great: return "great";
        case Status::NotGreat: return "not great";
    }
    CORRADE_ASSERT_UNREACHABLE("status is neither great nor non-great", {});
}

You can override this implementation by placing your own #define CORRADE_ASSERT_UNREACHABLE before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.

#define CORRADE_INTERNAL_ASSERT(condition)

Internal assertion macro.

Unlike CORRADE_ASSERT() usable for sanity checks on internal state, as it prints what failed and where instead of a user-friendly message.

By default, if assertion fails, failed condition, file and line is printed to error output and the application aborts. If CORRADE_STANDARD_ASSERT is defined, this macro expands to assert(condition). If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro expands to do {} while(false). Example usage:

CORRADE_INTERNAL_ASSERT(pos < size());

#define CORRADE_INTERNAL_CONSTEXPR_ASSERT(condition)

Internal constexpr assertion macro.

Unlike CORRADE_INTERNAL_ASSERT() this macro can be used in C++11 constexpr functions like this:

constexpr int divide(int a, int b) {
    return CORRADE_INTERNAL_CONSTEXPR_ASSERT(b), a/b;
}

In a constexpr context, if assertion fails, the code fails to compile. In a non- constexpr context, if assertion fails, failed condition, file and line is printed to error output and the application aborts. If CORRADE_STANDARD_ASSERT is defined, the standard assert() is called if condition fails. If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro expands to static_cast<void>(0).

You can override this implementation by placing your own #define CORRADE_INTERNAL_CONSTEXPR_ASSERT before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.

#define CORRADE_INTERNAL_ASSERT_OUTPUT(call)

Internal call output assertion macro.

Unlike CORRADE_INTERNAL_ASSERT(), this macro performs the call even if CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), making it usable for checking function output. Otherwise the behavior is the same as with CORRADE_INTERNAL_ASSERT(). Example usage:

CORRADE_INTERNAL_ASSERT_OUTPUT(initialize());

You can override this implementation by placing your own #define CORRADE_INTERNAL_ASSERT_OUTPUT before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.

#define CORRADE_INTERNAL_ASSERT_EXPRESSION(...) new in Git master

Internal expression assertion macro.

A variant of CORRADE_INTERNAL_ASSERT_OUTPUT() that can be used inside expressions. Useful in cases where creating a temporary just for the assertion would be too inconvenient — for example, the following code, which uses CORRADE_INTERNAL_ASSERT_OUTPUT() to check that the file was read correctly:

Containers::Optional<Containers::Array<char>> data;
CORRADE_INTERNAL_ASSERT_OUTPUT(data = Utility::Path::read("file.dat"));
consume(*std::move(data));

Could be rewritten in a shorter way and without having to use std::move() to pass a r-value with CORRADE_INTERNAL_ASSERT_EXPRESSION():

consume(*CORRADE_INTERNAL_ASSERT_EXPRESSION(Utility::Path::read("file.dat")));

The macro passes the expression to a function which asserts it evaluates to true and then returns the value forwarded. That implies the expression result type has to be at least movable. If CORRADE_STANDARD_ASSERT is defined, this macro uses assert(value) inside, unfortunately it's not possible for the standard assert macro to show the expression. If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro expands to nothing, leaving just the parenthesized expression out of it.

You can override this implementation by placing your own #define CORRADE_INTERNAL_ASSERT_EXPRESSION before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.

#define CORRADE_INTERNAL_ASSERT_UNREACHABLE() new in 2020.06

Internal assert that the code is unreachable.

Compared to CORRADE_ASSERT_UNREACHABLE(), usable for sanity checks on internal state, as it prints what failed and where instead of a user-friendly message.

By default, if code marked with this macro is reached, message with file and line is printed to error output and the application aborts. If CORRADE_STANDARD_ASSERT is defined, this macro expands to assert(!"unreachable code"). If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro hints to the compiler that given code is not reachable, possibly helping the optimizer (using a compiler builtin on GCC, Clang and MSVC; calling CORRADE_ASSERT_ABORT(), which is std::abort() by default, otherwise). A return statement can thus be safely omitted in a code path following this macro without causing any compiler warnings or errors. Example usage:

std::size_t elementCount(std::size_t size, Type type) {
    switch(type) {
        case Type::UnsignedInt: return size/4;
        case Type::UnsignedShort: return size/2;
        case Type::UnsignedByte: return size/1;
    }
    CORRADE_INTERNAL_ASSERT_UNREACHABLE();
}

You can override this implementation by placing your own #define CORRADE_INTERNAL_ASSERT_UNREACHABLE before including the Corrade/Utility/Assert.h header. See also CORRADE_ASSERT_ABORT(), CORRADE_ASSERT_MESSAGE_ABORT() and CORRADE_ASSERT_INCLUDE for a way to override behavior for all assertions at once.