Generic Macros

About

The MAXON API 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