debugging macros and functions

useful macros and functions for error checking and defensive programming. wxwidgets defines three families of the assert-like macros: the wxassert and wxfail macros only do anything if __wxdebug__ is defined (in other words, in the debug build) but disappear completely in the release build. on the other hand, the wxcheck macros stay event in release builds but a check failure doesn't generate any user-visible effects then. finally, the compile time assertions don't happen during the run-time but result in the compilation error messages if the condition they check fail.

include files

::wxonassert
wxassert
wxassert_min_bitsize
wxassert_msg
wxcompile_time_assert
wxcompile_time_assert2
wxfail
wxfail_msg
wxcheck
wxcheck_msg
wxcheck_ret
wxcheck2
wxcheck2_msg
::wxtrap
::wxisdebuggerrunning

::wxonassert

void wxonassert(const char *filename, int linenumber, const char *func, const char *cond, const char *msg = null)

this function is called whenever one of debugging macros fails (i.e. condition is false in an assertion). it is only defined in the debug mode, in release builds the wxcheck failures don't result in anything.

to override the default behaviour in the debug builds which is to show the user a dialog asking whether he wants to abort the program, continue or continue ignoring any subsequent assert failures, you may override wxapp::onassertfailure which is called by this function if the global application object exists.

wxassert

wxassert(condition)

assert macro. an error message will be generated if the condition is false in debug mode, but nothing will be done in the release build.

please note that the condition in wxassert() should have no side effects because it will not be executed in release mode at all.

see also

wxassert_msg,
wxcompile_time_assert

wxassert_min_bitsize

wxassert_min_bitsize(type, size)

this macro results in a compile time assertion failure if the size of the given type type is less than size bits.

you may use it like this, for example:

    // we rely on the int being able to hold values up to 2^32
    wxassert_min_bitsize(int, 32);

    // can't work with the platforms using utf-8 for wchar_t
    wxassert_min_bitsize(wchar_t, 16);

wxassert_msg

wxassert_msg(condition, msg)

assert macro with message. an error message will be generated if the condition is false.

see also

wxassert,
wxcompile_time_assert

wxcompile_time_assert

wxcompile_time_assert(condition, msg)

using wxcompile_time_assert results in a compilation error if the specified condition is false. the compiler error message should include the msg identifier - please note that it must be a valid c++ identifier and not a string unlike in the other cases.

this macro is mostly useful for testing the expressions involving the sizeof operator as they can't be tested by the preprocessor but it is sometimes desirable to test them at the compile time.

note that this macro internally declares a struct whose name it tries to make unique by using the __line__ in it but it may still not work if you use it on the same line in two different source files. in this case you may either change the line in which either of them appears on or use the wxcompile_time_assert2 macro.

also note that microsoft visual c++ has a bug which results in compiler errors if you use this macro with 'program database for edit and continue' (/zi) option, so you shouldn't use it ('program database' (/zi) is ok though) for the code making use of this macro.

see also

wxassert_msg,
wxassert_min_bitsize

wxcompile_time_assert2

wxcompile_time_assert(condition, msg, name)

this macro is identical to wxcompile_time_assert2 except that it allows you to specify a unique name for the struct internally defined by this macro to avoid getting the compilation errors described above.

wxfail

wxfail()

will always generate an assert error if this code is reached (in debug mode).

wxfail_msg

wxfail_msg(msg)

will always generate an assert error with specified message if this code is reached (in debug mode).

this macro is useful for marking unreachable" code areas, for example it may be used in the "default:" branch of a switch statement if all possible cases are processed above.

see also

wxfail

wxcheck

wxcheck(condition, retvalue)

checks that the condition is true, returns with the given return value if not (fails in debug mode). this check is done even in release mode.

wxcheck_msg

wxcheck_msg(condition, retvalue, msg)

checks that the condition is true, returns with the given return value if not (fails in debug mode). this check is done even in release mode.

this macro may be only used in non-void functions, see also wxcheck_ret.

wxcheck_ret

wxcheck_ret(condition, msg)

checks that the condition is true, and returns if not (fails with given error message in debug mode). this check is done even in release mode.

this macro should be used in void functions instead of wxcheck_msg.

wxcheck2

wxcheck2(condition, operation)

checks that the condition is true and wxfail and execute operation if it is not. this is a generalisation of wxcheck and may be used when something else than just returning from the function must be done when the condition is false.

this check is done even in release mode.

wxcheck2_msg

wxcheck2(condition, operation, msg)

this is the same as wxcheck2, but wxfail_msg with the specified msg is called instead of wxfail() if the condition is false.

::wxtrap

void wxtrap()

in debug mode (when __wxdebug__ is defined) this function generates a debugger exception meaning that the control is passed to the debugger if one is attached to the process. otherwise the program just terminates abnormally.

in release mode this function does nothing.

include files

::wxisdebuggerrunning

bool wxisdebuggerrunning()

returns true if the program is running under debugger, false otherwise.

please note that this function is currently only implemented for win32 and mac builds using codewarrior and always returns false elsewhere.