Corrade/Utility/Assert.h file

Macro CORRADE_ASSERT(), CORRADE_CONSTEXPR_ASSERT(), CORRADE_ASSERT_OUTPUT(), CORRADE_INTERNAL_ASSERT(), CORRADE_INTERNAL_CONSTEXPR_ASSERT(), CORRADE_INTERNAL_ASSERT_OUTPUT(), CORRADE_ASSERT_UNREACHABLE(), CORRADE_NO_ASSERT, CORRADE_GRACEFUL_ASSERT, CORRADE_STANDARD_ASSERT.

Contents

Defines

#define CORRADE_NO_ASSERT
Disable all assertions.
#define CORRADE_GRACEFUL_ASSERT
Gracefully print assertions.
#define CORRADE_STANDARD_ASSERT
Use standard assert.
#define CORRADE_ASSERT(condition, message, returnValue)
Assertion macro.
#define CORRADE_CONSTEXPR_ASSERT(condition, message)
Constexpr assertion macro.
#define CORRADE_ASSERT_OUTPUT(call, message, returnValue)
Call output assertion macro.
#define CORRADE_INTERNAL_ASSERT(condition)
Internal assertion macro.
#define CORRADE_INTERNAL_CONSTEXPR_ASSERT(condition)
Internal constexpr assertion macro.
#define CORRADE_INTERNAL_ASSERT_OUTPUT(call)
Internal call output assertion macro.
#define CORRADE_ASSERT_UNREACHABLE()
Assert that the following code is unreachable.

Define documentation

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

Parameters
condition Assert condition
message Message on assertion fail
returnValue Return value on assertion fail

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, the message is printed and the function returns with returnValue. 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(), {});

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

#define CORRADE_CONSTEXPR_ASSERT(condition, message)

Constexpr assertion macro.

Parameters
condition Assert condition
message Message on assertion fail

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, the message is printed and the rest of the function gets executed as usual. 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.

Parameters
call Assert call
message Message on assertion fail
returnValue Return value on assertion fail

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_INTERNAL_ASSERT(condition)

Internal assertion macro.

Parameters
condition Assert condition

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

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

#define CORRADE_INTERNAL_CONSTEXPR_ASSERT(condition)

Internal constexpr assertion macro.

Parameters
condition Assert condition

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.

Parameters
call Assert call

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

Assert that the following code is unreachable.

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(false). 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 improving performance. Example usage:

switch(flag) {
    case Flag::A: return foo;
    case Flag::B: return bar;
}

CORRADE_ASSERT_UNREACHABLE();

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