Module assert

Available on crate feature dep_sdl3 only.

A helpful assertion macro!

SDL assertions operate like your usual assert macro, but with some added features:

• It uses a trick with the sizeof operator, so disabled assertions vaporize out of the compiled code, but variables only referenced in the assertion won’t trigger compiler warnings about being unused.
• It is safe to use with a dangling-else: if (x) SDL_assert(y); else do_something();
• It works the same everywhere, instead of counting on various platforms’ compiler and C runtime to behave.
• It provides multiple levels of assertion ([SDL_assert], [SDL_assert_release], [SDL_assert_paranoid]) instead of a single all-or-nothing option.
• It offers a variety of responses when an assertion fails (retry, trigger the debugger, abort the program, ignore the failure once, ignore it for the rest of the program’s run).
• It tries to show the user a dialog by default, if possible, but the app can provide a callback to handle assertion failures however they like.
• It lets failed assertions be retried. Perhaps you had a network failure and just want to retry the test after plugging your network cable back in? You can.
• It lets the user ignore an assertion failure, if there’s a harmless problem that one can continue past.
• It lets the user mark an assertion as ignored for the rest of the program’s run; if there’s a harmless problem that keeps popping up.
• It provides statistics and data on all failed assertions to the app.
• It allows the default assertion handler to be controlled with environment variables, in case an automated script needs to control it.
• It can be used as an aid to Clang’s static analysis; it will treat SDL assertions as universally true (under the assumption that you are serious about the asserted claims and that your debug builds will detect when these claims were wrong). This can help the analyzer avoid false positives.

To use it: compile a debug build and just sprinkle around tests to check your code!

Structs

SDL_AssertData

Information about an assertion failure.

SDL_AssertState

Possible outcomes from a triggered assertion.

Constants

SDL_ASSERTION_ABORT

Terminate the program.

SDL_ASSERTION_ALWAYS_IGNORE

Ignore the assert from now on.

SDL_ASSERTION_BREAK

Make the debugger trigger a breakpoint.

SDL_ASSERTION_IGNORE

Ignore the assert.

SDL_ASSERTION_RETRY

Retry the assert immediately.

SDL_ASSERT_LEVEL

Functions

SDL_AssertBreakpoint^⚠

SDL_GetAssertionHandler^⚠

Get the current assertion handler.

SDL_GetAssertionReport^⚠

Get a list of all assertion failures.

SDL_GetDefaultAssertionHandler^⚠

Get the default assertion handler.

SDL_ReportAssertion^⚠

Never call this directly.

SDL_ResetAssertionReport^⚠

Clear the list of all assertion failures.

SDL_SetAssertionHandler^⚠

Set an application-defined assertion handler.

SDL_TriggerBreakpoint^⚠

Type Aliases

SDL_AssertionHandler

A callback that fires when an SDL assertion fails.