CategoryAssert
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!
Functions
Datatypes
Structs
Enums
Macros
CategoryAPICategory