Generic Macros

About

The MAXON API ALIASES makes heavy use of C++ preprocessor macros. These macros are used to automatically create code or to mark parts of the code (e.g. in interfaces). The macros described on this page are relevant for every kind of development. Other specialised macros exist for special tasks.

Object Use

Under Xcode / GCC the compiler can check if the return value of a function is used or not. If a return value that should be used is not used, a compile error is thrown.

Note
Do not use these macros to mute errors returned with the error system. Instead use iferr_cannot_fail() or iferr_ignore(). See Error Handling.
//----------------------------------------------------------------------------------------
// A critical function. Success must always be checked.
//----------------------------------------------------------------------------------------
MAXON_WARN_UNUSED static maxon::Bool CriticalFunction();
// This example shows the function call without and with handling the return value.
// this will trigger a compile error
CriticalFunction();
// this won't trigger a compile error
const maxon::Bool res = CriticalFunction();
// this won't trigger a compile error
MAXON_WARN_MUTE_UNUSED CriticalFunction();
  • MAXON_WARN_UNUSED_CLASS: If a class marked with this macro is used as a return value but this return value is not used, an error is thrown.
// This example shows a simple structure.
// It is marked with MAXON_WARN_UNUSED_CLASS,
// so when used as return value, this
// return value must be handled.
// A CriticalInfo.
struct MAXON_WARN_UNUSED_CLASS CriticalInfo
{
maxon::Int32 _info;
};
// This function returns a CriticalInfo.
static CriticalInfo GetCriticalInfo();
// This example shows how the return value of the type of a MAXON_WARN_UNUSED_CLASS
// marked class must be handled to avoid a compile error.
// this will trigger a compile error
GetCriticalInfo();
// this won't trigger a compile error
const CriticalInfo info = GetCriticalInfo();
DiagnosticOutput("Info: @", info._info);

If a variable is declared but not used this will trigger a compile warning. This warning can be suppressed with this function:

  • maxon::UseVariable(): Uses the given variable.
Note
Using maxon::UseVariable() will not cause any performance penalty.
// This example shows how an unused variable triggers a warning and how this warning is silenced.
{
// this will trigger a compile warning that "number" is not used
const maxon::Int number = GetNumber();
}
{
// this won't trigger a warning
const maxon::Int number = GetNumber();
maxon::UseVariable(number);
}

Program Flow and Structure

These macros are used to mark certain parts of the source code:

  • MAXON_SCOPE: Marks a block of code that is scoped for a certain reason.
  • MAXON_UNLIKELY: Marks an unlikely branch for branch prediction.
  • MAXON_LIKELY: Marks a likely branch for branch prediction.
// This example uses the MAXON_SCOPE macro to mark two blocks of code
// that use the same variable names.
{
const maxon::Int key = 0;
maxon::Int number = data.Get(key, 0);
number++;
data.Set(key, number) iferr_return;
}
{
const maxon::Int key = 1;
maxon::Int number = data.Get(key, 0);
number++;
data.Set(key, number) iferr_return;
}
// This example uses the MAXON_UNLIKELY to mark an unlikely case.
if (MAXON_UNLIKELY(number > 100))
{
number = 100;
}

Switch-case statements can be improved with:

// This example defines a custom enumeration and checks if all elements are used in a switch-statement.
enum class MyEnum
{
A,
B,
C
};
const MyEnum value = MyEnum::B;
switch (value)
{
case MyEnum::A:
ApplicationOutput("Value A");
break;
case MyEnum::B:
ApplicationOutput("Value B");
break;
default:
ApplicationOutput("No Value");
break;
}

Finally

The code defined in a "finally" block is executed when the program flow leaves the current scope.

  • finally: Defines a code block which is executed when the scope is left.
  • finally_once: Returns a maxon::FinallyOnce object that can be used to disable the code block execution.
// This example uses a "finally" block to ensure the allocated memory is deleted.
static maxon::Result<void> HandleMemory()
{
{
// make sure that the allocated data will be deleted in any case
};
ReadData(data) iferr_return;
WriteData(data) iferr_return;
return maxon::OK;
}

Enummerations

// This example shows the declaration of enumeration classes.
//----------------------------------------------------------------------------------------
//----------------------------------------------------------------------------------------
enum class PRIMARY_COLOR
{
RED = 1,
GREEN = 2,
BLUE = 3
} MAXON_ENUM_LIST(PRIMARY_COLOR);
//----------------------------------------------------------------------------------------
//----------------------------------------------------------------------------------------
enum class QUALITY
{
NONE = 0,
A = (1 << 0),
B = (1 << 1),
C = (1 << 2),
D = (1 << 3),
} MAXON_ENUM_FLAGS(QUALITY);
// This example shows how enumeration values are used.
// use simple enumeration
// set color
const PRIMARY_COLOR color = PRIMARY_COLOR::RED;
// check color
if (color == PRIMARY_COLOR::RED)
if (color != PRIMARY_COLOR::BLUE)
DiagnosticOutput("Color is not blue.");
// use bit flags
// define qualities
const QUALITY qualities = QUALITY::A | QUALITY::B;
// check qualities
if (qualities & QUALITY::A)
DiagnosticOutput("Qualitiy A set");
if (!(qualities & QUALITY::D))
DiagnosticOutput("Quality D not set");

Classes and Functions

The following macros are used to declare classes and their functions:

These macros are used to implement certain operators automatically:

// This example shows a custom class using various macros
// to improve the class' functionality.
class NumberClass
{
public:
MAXON_IMPLICIT NumberClass(maxon::Int v)
{
_number = v;
}
// define copy constructor
NumberClass(const NumberClass& src) : MAXON_COPY_MEMBERS(_number) { }
// define assign operator "=" from copy constructor
// define "==", "!=" operators and GetHashCode()
MAXON_OPERATOR_EQUALITY_HASHCODE(NumberClass, _number);
// accessors
const maxon::Int* GetNumber() const
{
return &_number;
}
maxon::Int* GetNumber()
{
return MAXON_NONCONST_COUNTERPART(GetNumber());
}
private:
maxon::Int _number;
};
// This example uses a class defined with various macros to implement
// a non-const access function and GetHashCode().
NumberClass someNumber(1);
// edit
maxon::Int* const number = someNumber.GetNumber();
*number = *number + 1;
// print
const maxon::Int* const res = someNumber.GetNumber();
DiagnosticOutput("Number: @", *res);
// hash
const maxon::UInt hash = someNumber.GetHashCode();
DiagnosticOutput("Hash: @", hash);
// copy
NumberClass someOtherNumber(0);
someOtherNumber = someNumber;

Utility

Other utility macros exist:

// This example uses various utility macros.
// prints the value of the macro SOME_VALUE
const maxon::String value(MAXON_STRINGIFY(SOME_VALUE));
DiagnosticOutput("Some Value: @", value);
// print the hash of the given values
const maxon::Int i = 123;
const maxon::Float f = 132.0;
const maxon::UInt hash = MAXON_HASHCODE(i, f);
DiagnosticOutput("Hash: @", hash);

Further Reading

MAXON_OPERATOR_COPY_ASSIGNMENT
#define MAXON_OPERATOR_COPY_ASSIGNMENT(TypeName)
Definition: classhelpers.h:381
MAXON_SWITCH_CHECKALLENUMS_END
#define MAXON_SWITCH_CHECKALLENUMS_END
Definition: compilerdetection.h:419
NewMemClear
#define NewMemClear(T, cnt)
Definition: defaultallocator.h:204
MAXON_IMPLICIT
#define MAXON_IMPLICIT
Definition: apibase.h:174
MAXON_ENUM_FLAGS
#define MAXON_ENUM_FLAGS(E,...)
Definition: enumflags.h:192
finally
#define finally
Definition: finally.h:64
MAXON_WARN_UNUSED
#define MAXON_WARN_UNUSED
Definition: compilerdetection.h:321
maxon::String
Definition: string.h:1225
maxon::OK
return OK
Definition: apibase.h:2620
BLUE
BLUE
Definition: lib_birender.h:67
maxon::Bool
bool Bool
boolean type, possible values are only false/true, 8 bit
Definition: apibase.h:183
iferr_return
#define iferr_return
Definition: resultbase.h:1465
MAXON_HASHCODE
#define MAXON_HASHCODE(...)
MAXON_HASHCODE computes the hash code of the arguments based on DefaultCompare::GetCombinedHashCode.
Definition: classhelpers.h:476
maxon::Float
Float64 Float
Definition: apibase.h:199
GREEN
GREEN
Definition: lib_birender.h:66
MAXON_OPERATOR_EQUALITY_HASHCODE
#define MAXON_OPERATOR_EQUALITY_HASHCODE(T,...)
Definition: classhelpers.h:522
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
MAXON_UNLIKELY
#define MAXON_UNLIKELY(X)
Definition: compilerdetection.h:486
maxon::src
const T & src
Definition: apibase.h:2613
maxon::Result< void >
maxon::Int32
int32_t Int32
32 bit signed integer datatype.
Definition: apibase.h:178
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:190
iferr_scope
#define iferr_scope
Definition: resultbase.h:1374
maxon::DeleteMem
void DeleteMem(T *&p)
Definition: defaultallocator.h:257
RED
RED
Definition: lib_birender.h:65
MDDIRTY::NONE
@ NONE
MAXON_SWITCH_CHECKALLENUMS_BEGIN
#define MAXON_SWITCH_CHECKALLENUMS_BEGIN
Definition: compilerdetection.h:418
ApplicationOutput
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
MAXON_WARN_MUTE_UNUSED
#define MAXON_WARN_MUTE_UNUSED
The MAXON_WARN_MUTE_UNUSED macro is deprecated. Please use iferr_ignore or iferr_cannot_fail and spec...
Definition: compilerdetection.h:325
MAXON_WARN_UNUSED_CLASS
#define MAXON_WARN_UNUSED_CLASS
Definition: compilerdetection.h:322
MAXON_ENUM_LIST
#define MAXON_ENUM_LIST(E,...)
Definition: enumflags.h:137
maxon::Char
char Char
signed 8 bit character
Definition: apibase.h:186
maxon::UInt
UInt64 UInt
unsigned 32/64 bit int, size depends on the platform
Definition: apibase.h:191
MAXON_COPY_MEMBERS
#define MAXON_COPY_MEMBERS(...)
Definition: classhelpers.h:466
MAXON_NONCONST_COUNTERPART
#define MAXON_NONCONST_COUNTERPART(...)
Definition: classhelpers.h:586
MAXON_SCOPE
#define MAXON_SCOPE
Definition: apibase.h:2798