Kanzi  3.9.9
Kanzi Engine C++ API
Assertion macros

In the debug build, use assertion macros to terminate the application and log the error message when the assertion is failed. More...

Collaboration diagram for Assertion macros:

Macros

#define kzAssert(expression)
 In the debug build, if assertion expression evaluates to false, use this macro to terminate the application and log the error message. More...
 
#define kzAssertMessage(expression, message)
 In the debug build, if the assertion expression evaluates to false, use this macro to terminate the application and log the error message including the description message you provided. More...
 
#define kzAssertUnreachable()
 In the debug build, use this macro to terminate the application and log the error message. More...
 
#define kzAssertUnreachableMessage(message)
 In the debug build, use this macro to terminate the application and log the error message including the description message you provided. More...
 
#define kzDebugBreak()
 In the debug build, when you attach the debugger, use this macro to trigger a breakpoint. More...
 

Detailed Description

In the debug build, use assertion macros to terminate the application and log the error message when the assertion is failed.

To assert expressions use kzAssert and kzAssertMessage macros.

To assert unreachable code paths use kzAssertUnreachable and kzAssertUnreachableMessage.

To insert a breakpoint use kzDebugBreak.

Note
The assertion macros use the Logging subsystem to log the errors.

Macro Definition Documentation

#define kzAssert (   expression)

In the debug build, if assertion expression evaluates to false, use this macro to terminate the application and log the error message.

The error message includes the file name and the line number where the assertion failed.

If you want to include in the error message the description, which makes it easier to understand why assertion failed, use kzAssertMessage.

For compile-time assertion, use KZ_STATIC_ASSERT.

Note
In the release build the calls to this macro are removed during preprocessing.
Parameters
expressionThe assertion expression.

Example

To terminate an application when assertion fails:

int testValue = 3;
// Because the expression testValue == 5 is false, an application is terminated and the error message is logged.
kzAssert(testValue == 5);
#define kzAssertMessage (   expression,
  message 
)

In the debug build, if the assertion expression evaluates to false, use this macro to terminate the application and log the error message including the description message you provided.

The error message includes the description message you provided and the file name and the line number where the assertion failed.

For compile-time assertion, use KZ_STATIC_ASSERT.

Note
In the release build the calls to this macro are removed during preprocessing.
Parameters
expressionThe assertion expression.
messageThe description message you want to include in the error message. For the format description see Log message formatting.

Example

To terminate an application when assertion fails and include in the log message a description of why the assertion failed:

// Because the expression testValue == 5 is false, an application is terminated and the error message is logged.
// The error message includes a description, containing the value of the 'testValue' variable.
kzAssertMessage(testValue == 5, ("The assertion failed because testValue = {}", testValue));
#define kzAssertUnreachable ( )

In the debug build, use this macro to terminate the application and log the error message.

Use this macro to assert the execution of the code which must not be reached by any valid code path. The error message includes the file name and the line number where the assertion failed.

If you want to include in the error message additional description message, which makes it easier to understand why the assertion failed, use kzAssertUnreachableMessage.

Note
In the release build the behavior of this macro is undefined.

Example

To terminate an application and write an error message:

// Because the execution reached this code, an application is terminated and the error message is logged.
#define kzAssertUnreachableMessage (   message)

In the debug build, use this macro to terminate the application and log the error message including the description message you provided.

The error message includes the description message you provided and the file name and the line number where the assertion failed.

Note
In the release build the behavior of this macro is undefined.
Parameters
messageThe description message you want to include in the error message. For the format description see Log message formatting.

Example

To terminate an application when assertion fails and include in the log message a description of why the assertion failed:

enum Color
{
BLACK,
WHITE
};
int color = BLACK;
// For example, bug in the application changes the value of the 'color' variable.
color = 4;
switch(color)
{
case BLACK:
// Handle this case.
break;
case WHITE:
// Handle this case.
break;
default:
// Because the execution reached this code, an application is terminated and the error message is logged.
// The error message includes a description, containing the value of the 'color' variable.
kzAssertUnreachableMessage(("Unexpected value of color {}.", color));
break;
}
#define kzDebugBreak ( )

In the debug build, when you attach the debugger, use this macro to trigger a breakpoint.

If you do not attach the debugger, the execution continues without interruption.

Note
In the release build the calls to this macro are removed during preprocessing.