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_INTERNAL_ASSERT(), CORRADE_INTERNAL_CONSTEXPR_ASSERT(), CORRADE_INTERNAL_ASSERT_OUTPUT() and CORRADE_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 does not call std::abort(). Useful for testing assertion behavior. See documentation of CORRADE_ASSERT(), CORRADE_CONSTEXPR_ASSERT() and CORRADE_ASSERT_OUTPUT() for detailed description of given macro behavior. The CORRADE_INTERNAL_ASSERT(), CORRADE_INTERNAL_CONSTEXPR_ASSERT(), CORRADE_INTERNAL_ASSERT_OUTPUT() and CORRADE_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.

#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_INTERNAL_ASSERT(), CORRADE_INTERNAL_CONSTEXPR_ASSERT(), CORRADE_INTERNAL_ASSERT_OUTPUT() and CORRADE_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(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 compiles to assert(condition), ignoring message. If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro compiles to do {} while(0). 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.empty(), "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(), {});

#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 compiles 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.

#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.

#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 compiles 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 std::abort() otherwise). 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.

#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 compiles to assert(condition). If CORRADE_NO_ASSERT is defined (or if both CORRADE_STANDARD_ASSERT and NDEBUG are defined), this macro compiles to do {} while(0). 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 compiles 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.

#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.

#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::Array<char> data;
CORRADE_INTERNAL_ASSERT_OUTPUT(data = Utility::Directory::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::Directory::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 compiles 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.

#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 compiles 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 std::abort() otherwise). 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.

#define CORRADE_ASSUME(condition) new in 2020.06

Assume a condition.

Compared to CORRADE_INTERNAL_ASSERT() this macro does not handle the case when the condition isn't true in any way — only provides a hint to the compiler, possibly improving performance. Uses a compiler builtin on GCC, Clang and MSVC; expands to an empty do while otherwise. Example usage:

CORRADE_ASSUME(src != dst);
for(; src != end; ++src, ++dst) *dst += *src;

You can override this implementation by placing your own #define CORRADE_ASSUME before including the Corrade/Utility/Assert.h header.