Corrade/Utility/Macros.h file

Macro CORRADE_DEPRECATED(), CORRADE_DEPRECATED_ALIAS(), CORRADE_DEPRECATED_NAMESPACE(), CORRADE_DEPRECATED_ENUM(), CORRADE_DEPRECATED_FILE(), CORRADE_DEPRECATED_MACRO(), CORRADE_IGNORE_DEPRECATED_PUSH, CORRADE_IGNORE_DEPRECATED_POP, CORRADE_UNUSED, CORRADE_ALIGNAS(), CORRADE_NORETURN, CORRADE_THREAD_LOCAL, CORRADE_ALWAYS_INLINE, CORRADE_NEVER_INLINE, CORRADE_FUNCTION, CORRADE_LINE_STRING, CORRADE_AUTOMATIC_INITIALIZER(), CORRADE_AUTOMATIC_FINALIZER()

Contents

Defines

#define CORRADE_DEPRECATED(message)
Deprecation mark.
#define CORRADE_DEPRECATED_ALIAS(message)
Alias deprecation mark.
#define CORRADE_DEPRECATED_NAMESPACE(message)
Namespace deprecation mark.
#define CORRADE_DEPRECATED_ENUM(message)
Enum deprecation mark.
#define CORRADE_DEPRECATED_FILE(message)
File deprecation mark.
#define CORRADE_DEPRECATED_MACRO(macro, message)
Macro deprecation mark.
#define CORRADE_IGNORE_DEPRECATED_PUSH
Begin code section with deprecation warnings ignored.
#define CORRADE_IGNORE_DEPRECATED_POP
End code section with deprecation warnings ignored.
#define CORRADE_UNUSED
Unused variable mark.
#define CORRADE_ALIGNAS(alignment)
Type alignment specifier.
#define CORRADE_NORETURN
Noreturn fuction attribute.
#define CORRADE_THREAD_LOCAL
Thread-local annotation.
#define CORRADE_ALWAYS_INLINE
Always inline a function.
#define CORRADE_NEVER_INLINE
Never inline a function.
#define CORRADE_FUNCTION
Function name.
#define CORRADE_LINE_STRING
Line number as a string.
#define CORRADE_AUTOMATIC_INITIALIZER(function)
Automatic initializer.
#define CORRADE_AUTOMATIC_FINALIZER(function)
Automatic initializer.

Define documentation

#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") Output<5> Buzz;

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):

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.

GCC claims support since version 4.9, but even in version 8.2 it only emits an "attribute ignored" warning at the declaration location and no diagnostic when such namespace is used — which is practically useless (source).

#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;
}

#define CORRADE_ALIGNAS(alignment)

Type alignment specifier.

Expands to C++11 alignas() specifier on supported compilers, otherwise falls back to compiler-specific attribute. Example usage:

CORRADE_ALIGNAS(4) char data[16]; // so it can be read as 32-bit integers

#define CORRADE_NORETURN

Noreturn fuction attribute.

Expands to C++11 [[noreturn]] attribute on supported compilers, otherwise falls back to compiler-specific attribute. Example usage:

CORRADE_NORETURN void exit42() { std::exit(42); }

#define CORRADE_THREAD_LOCAL

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_ALWAYS_INLINE

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

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_FUNCTION

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

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_AUTOMATIC_INITIALIZER(function)

Automatic initializer.

Parameters
function Initializer function name of type int(*)().

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

#define CORRADE_AUTOMATIC_FINALIZER(function)

Automatic initializer.

Parameters
function Finalizer function name of type int(*)().

Function passed as argument will be called even before entering main() function. This is usable in conjuction with CORRADE_AUTOMATIC_INITIALIZER() when there is need to properly discard initialized data.