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

kzAssert

#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

expression

The 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); 
        

kzAssertMessage

#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

expression	The assertion expression.
message	The 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));

kzAssertUnreachable

#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.
        kzAssertUnreachable();

kzAssertUnreachableMessage

#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

message

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

kzDebugBreak

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