Corrade/Utility/Macros.h file

#define CORRADE_UNUSED

Unused variable mark.

Putting this before unused variable will suppress compiler warning about it being unused. If possible, use static_cast<void>(var) or nameless function parameters instead.

int foo(int a, CORRADE_UNUSED int b) {
    return a;
}

Defined as the C++17 [[maybe_unused]] attribute on GCC >= 10, with a compiler-specific variant on Clang, MSVC and older GCC. Clang and MSVC have their own specific macro always as they otherwise complain about use of a C++17 feature when compiling as C++11 or C++14.

#define CORRADE_NODISCARD(message) new in Git master

Return value shouldn't be discarded.

Putting this before return type of a function will cause a compiler warning if the function is called without using the returned value.

CORRADE_NODISCARD("file needs closing after") std::FILE*
    openFile(Containers::StringView name);

Defined as the [[nodiscard(message)]] attribute if compiling as C++20 or newer, [[nodiscard]] with message ignored if compiling as C++17, and with a compiler-specific variant and message ignored on Clang, MSVC and GCC, empty otherwise.

Note that on MSVC the fallback _Check_return_ attribute requires building with /analyze, otherwise no diagnostics is issued if the return value is unused.

#define CORRADE_FALLTHROUGH new in 2020.06

Switch case fall-through.

Suppresses a warning about a case fallthrough in a switch. Expected to be put at a place where a break; would usually be:

switch(a) {
    case 2:
        *b++ = *c++;
        CORRADE_FALLTHROUGH
    case 1:
        *b++ = *c++;
};

Defined as the C++17 [[fallthrough]] attribute on GCC >= 7, Clang has its own specific macro as it complains about use of a C++17 feature when compiling as C++11 or C++14. On MSVC there's no pre-C++17 alternative so it's non-empty only on 2019 16.6+ and only if compiling under C++17, as it warns otherwise as well. Defined as empty on older GCC and MSVC — these versions don't warn about the fallthrough, so there's no need to suppress anything.

#define CORRADE_ALIGNAS(alignment)

Type alignment specifier.

#define CORRADE_NORETURN

Noreturn fuction attribute.

#define CORRADE_THREAD_LOCAL new in 2019.10

Thread-local annotation.

Expands to C++11 thread_local keyword on all compilers except old Apple Clang, where it's defined as __thread. Note that the pre-standard __thread has some semantic differences, in particular regarding RAII.

#define CORRADE_CONSTEXPR14 new in 2020.06

C++14 constexpr.

Expands to constexpr if C++14 or newer standard is enabled and if the compiler implements C++14 relaxed constexpr rules (which includes GCC 5+, Clang 3.5+ and MSVC 2017+), empty otherwise. Useful for selectively marking functions that make use of C++14 constexpr.

#define CORRADE_CONSTEXPR20 new in Git master

C++20 constexpr.

Expands to constexpr if C++20 or newer standard is enabled and if the compiler implements all C++20 constexpr language additions such as trivial default initialization (which includes GCC 10+, Clang 10+ and MSVC 2019 19.29+), empty otherwise. Useful for selectively marking functions that make use of C++20 constexpr.

#define CORRADE_ALWAYS_INLINE new in 2019.10

Always inline a function.

Stronger than the standard inline keyword where supported, but even then the compiler might decide to not inline the function (for example if it's recursive). Expands to __attribute__((always_inline)) inline on GCC and Clang (both keywords need to be specified, docs), to __forceinline on MSVC (docs) and to just inline elsewhere. On GCC and Clang this makes the function inline also in Debug mode (-g), while on MSVC compiling in Debug (/Ob0) always suppresses all inlining. Example usage:

CORRADE_ALWAYS_INLINE int addOne(int a);

#define CORRADE_NEVER_INLINE new in 2019.10

Never inline a function.

Prevents the compiler from inlining a function during an optimization pass. Expands to __attribute__((noinline)) on GCC and Clang (docs), to __declspec(noinline) on MSVC (docs) and is empty elsewhere. Example usage:

CORRADE_NEVER_INLINE void testFunctionCallOverhead();

#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/Macros.h header.

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

Mark an if condition as likely to happen.

Since branch predictors of contemporary CPUs do a good enough job already, the main purpose of this macro is to affect assembly generation and instruction cache use in hot loops — for example, when a certain condition is likely to happen each iteration, the compiler may put code of the else branch in a "cold" section of the code, ensuring the more probable code path stays in the cache:

float* in = …;
float* out = …;
Containers::BitArray mask = …;
for(std::size_t i = 0; i != size; ++i) {
    if CORRADE_LIKELY(mask[i]) {
        out[i] = in[i];
    } else {
        out[i] = std::acos(in[i]);
    }
}

Defined as the C++20 [[likely]] attribute on GCC >= 10 (and on Clang 12 and MSVC 2019 16.6+ if compiling under C++20). On older versions of GCC and on Clang in C++11/14/17 mode the macro expands to __builtin_expect(); on older MSVC the macro is a pass-through.

It's recommended to use this macro only if profiling shows its advantage. While it may have no visible effect in most cases, wrong suggestion can lead to suboptimal performance. Similar effect can be potentially achieved by reordering the branches in a certain way, but the behavior is highly dependent on compiler-specific heuristics.

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

Mark an if condition as unlikely to happen.

An inverse to CORRADE_LIKELY(), see its documentation for more information about suggested use and expected impact on performance. Useful to mark boundary conditions in tight loops, for example:

float* data = …;
unsigned* indices = …;
unsigned previousIndex = ~unsigned{};
float factor = …;
for(std::size_t i = 0; i != size; ++i) {
    if CORRADE_UNLIKELY(indices[i] != previousIndex) {
        factor = someComplexOperation();
    }

    data[i] *= factor;
}

#define CORRADE_FUNCTION new in 2019.10

Function name.

Gives out an undecorated function name. Equivalent to the standard C++11 __func__ on all sane platforms and to __FUNCTION__ on Android, because it just has to be different.

Note that the function name is not a string literal, meaning it can't be concatenated with other string literals like __FILE__ or CORRADE_LINE_STRING. Details in this Stack Overflow answer.

#define CORRADE_LINE_STRING new in 2019.10

Line number as a string.

Turns the standard __LINE__ macro into a string. Useful for example to have correct line numbers when embedding GLSL shaders directly in the code:

const char* shader = "#line " CORRADE_LINE_STRING "\n" R"GLSL(
    in vec3 position;

    void main() {
        THIS_IS_AN_ERROR();
    }
)GLSL";

Depending on where the source string is located in the file, the potential error or warning messages from the shader compiler will show the errors for example like

1:97(4): error: no function with name 'THIS_IS_AN_ERROR'

instead of showing the line number relatively as 1:5(4). Note that GLSL in particular, unlike C, interprets the #line statement as applying to the immediately following line, which is why the extra "\n" is needed.

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

Passthrough.

Expands to all arguments passed to it. Inverse of CORRADE_NOOP().

#define CORRADE_NOOP(...) new in 2019.10

No-op.

Eats all arguments passed to it. Inverse of CORRADE_PASSTHROUGH(). Useful on compilers that don't support defining function macros on command line — for example, -DA_MACRO=CORRADE_NOOP is the same as doing -D'A_MACRO(arg)='.

#define CORRADE_AUTOMATIC_INITIALIZER(function)

Automatic initializer.

Function passed as argument will be called even before entering main() function. This is usable when e.g. automatically registering plugins or data resources without forcing the user to write additional code in main().

It's possible to override this macro for testing purposes or when global constructors are not desired. For a portable way to defining the macro out on compiler command line, see CORRADE_NOOP().

#define CORRADE_AUTOMATIC_FINALIZER(function)

Automatic finalizer.

Function passed as argument will be called after exiting the main() function. This is usable in conjunction with CORRADE_AUTOMATIC_INITIALIZER() when there is need to properly discard initialized data.

It's possible to override this macro for testing purposes or when global destructors are not desired. For a portable way to defining the macro out on compiler command line, see CORRADE_NOOP().