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

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

#define CORRADE_DEPRECATED_NAMESPACE(message)

Namespace deprecation mark.

Marked enum or enum value will emit deprecation warning on supported compilers (C++17 feature, MSVC 2015 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 7.3 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 2015, 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
};

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