Corrade/Utility/Macros.h file

#define CORRADE_DEPRECATED(message)

Deprecation mark.

Marked function, class or typedef will emit deprecation warning on supported compilers (GCC, Clang, MSVC):

class CORRADE_DEPRECATED("use Bar instead") Foo;
CORRADE_DEPRECATED("use bar() instead") void foo();
typedef CORRADE_DEPRECATED("use Fizz instead") Fizz Buzz;
CORRADE_DEPRECATED("use Value instead") constexpr int Vauel = 3;

Might not work for template aliases, namespaces and enum values on all compilers, use CORRADE_DEPRECATED_ALIAS(), CORRADE_DEPRECATED_NAMESPACE() and CORRADE_DEPRECATED_ENUM() instead. See CORRADE_DEPRECATED_FILE() for file-level deprecation and CORRADE_DEPRECATED_MACRO() for deprecating macros.

Note that on MSVC and GCC this doesn't warn when using nested names of deprecated classes or typedefs, only when the type is instantiated — i.e., DeprecatedStruct a; will warn, but DeprecatedStruct::Value will not.

#define CORRADE_DEPRECATED_ALIAS(message)

Alias deprecation mark.

Marked alias will emit deprecation warning on supported compilers (GCC, Clang, MSVC 2017+):

template<class T> using Foo CORRADE_DEPRECATED_ALIAS("use Bar instead") = Bar<T>;

Note that on MSVC and GCC this doesn't warn when using nested names of deprecated aliases, only when the type is instantiated — i.e., DeprecatedAlias a; will warn, but DeprecatedAlias::Value will not.

#define CORRADE_DEPRECATED_NAMESPACE(message)

Namespace deprecation mark.

Marked enum or enum value will emit deprecation warning on supported compilers (C++17 feature, MSVC and Clang, GCC 10+):

namespace CORRADE_DEPRECATED_NAMESPACE("use Bar instead") Foo {
    using namespace Bar;
}

Note that this doesn't work on namespace aliases (i.e., marking namespace Bar = Foo; with this macro will result in a compile error.

#define CORRADE_DEPRECATED_ENUM(message)

Enum deprecation mark.

Marked enum or enum value will emit deprecation warning on supported compilers (C++17 feature, MSVC 2017+, Clang and GCC 6+):

enum class CORRADE_DEPRECATED_ENUM("use Bar instead") Foo {};

enum class Bar {
    Fizz = 0,
    Buzz = 1,
    Baz CORRADE_DEPRECATED_ENUM("use Bar::Buzz instead") = 1
};

Note that on MSVC and GCC this doesn't warn when using values of deprecated enums, only when the enum is instantiated — i.e., DeprecatedEnum e; will warn, but DeprecatedEnum::Value will not. Moreover, on MSVC this doesn't warn when a enum value marked as deprecated is used. MSVC 2015 supports the annotation, but ignores it for both enums and enum values.

#define CORRADE_DEPRECATED_FILE(message)

File deprecation mark.

Putting this in a file will emit deprecation warning when given file is included or compiled (GCC 4.8, Clang, MSVC):

CORRADE_DEPRECATED_FILE("use Bar.h instead") // yes, no semicolon at the end

On Clang the message is prepended with this file is deprecated, which is not possible on GCC. Note that the warning is suppressed in case given directory is included as system (-isystem on GCC and Clang).

On MSVC the message is prepended with warning: <file> is deprecated. The message just appears in the log output without any association to a particular file, so the file is included in the message. Due to MSVC limitations, the message doesn't contribute to the warning log or warning count in any way.

#define CORRADE_DEPRECATED_MACRO(macro, message)

Macro deprecation mark.

Putting this in a macro definition will emit deprecation warning when given macro is used (GCC 4.8, Clang, MSVC):

#define MAKE_FOO(args) \
    CORRADE_DEPRECATED_MACRO(MAKE_FOO(),"use MAKE_BAR() instead") MAKE_BAR(args)

On Clang and MSVC the message is prepended with this macro is deprecated, which is not possible on GCC.

On MSVC the message is prepended with <file> warning: <macro> is deprecated, where the macro name is taken from the first argument. The message just appears in the log output without any association to a particular file, so the file is included in the message. Due to MSVC limitations, the message doesn't contribute to the warning log or warning count in any way.

#define CORRADE_IGNORE_DEPRECATED_PUSH

Begin code section with deprecation warnings ignored.

Suppresses compiler warnings when using a deprecated API (GCC, Clang, MSVC). Useful when testing or writing APIs that depend on deprecated functionality. In order to avoid warning suppressions to leak, for every CORRADE_IGNORE_DEPRECATED_PUSH there has to be a corresponding CORRADE_IGNORE_DEPRECATED_POP. Example usage:

CORRADE_DEPRECATED("use bar() instead") void foo(int);

CORRADE_IGNORE_DEPRECATED_PUSH
foo(42);
CORRADE_IGNORE_DEPRECATED_POP

In particular, warnings from CORRADE_DEPRECATED(), CORRADE_DEPRECATED_ALIAS(), CORRADE_DEPRECATED_NAMESPACE() and CORRADE_DEPRECATED_ENUM() are suppressed. The CORRADE_DEPRECATED_FILE() and CORRADE_DEPRECATED_MACRO() warnings are suppressed only on Clang.

#define CORRADE_IGNORE_DEPRECATED_POP

End code section with deprecation warnings ignored.

See CORRADE_IGNORE_DEPRECATED_PUSH for more information.

#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_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 = …;
std::vector<bool> 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().