interface/debug.h

   1 /////////////////////////////////////////////////////////////////////////////
   2     // Name:        debug.h
   3     // Purpose:     documentation for global functions
   4     // Author:      wxWidgets team
   5     // RCS-ID:      $Id$
   6     // Licence:     wxWindows license
   7     /////////////////////////////////////////////////////////////////////////////
   8
   9     /**
  10     Will always generate an assert error if this code is reached (in debug mode).
  11
  12     See also: wxFAIL_MSG
  13 */
  14 #define wxFAIL()     /* implementation is private */
  15
  16
  17     /**
  18     This function is called whenever one of debugging macros fails (i.e. condition
  19     is @false in an assertion). It is only defined in the debug mode, in release
  20     builds the wxCHECK failures don't result in anything.
  21
  22     To override the default behaviour in the debug builds which is to show the user
  23     a dialog asking whether he wants to abort the program, continue or continue
  24     ignoring any subsequent assert failures, you may override
  25     wxApp::OnAssertFailure which is called by this function if
  26     the global application object exists.
  27 */
  28 void wxOnAssert(const char * fileName, int lineNumber,
  29                 const char * func,
  30                 const char * cond,
  31                 const char * msg = @NULL);
  32
  33 /**
  34     In debug mode (when @c __WXDEBUG__ is defined) this function generates a
  35     debugger exception meaning that the control is passed to the debugger if one is
  36     attached to the process. Otherwise the program just terminates abnormally.
  37
  38     In release mode this function does nothing.
  39 */
  40 void wxTrap();
  41
  42 /**
  43     Will always generate an assert error with specified message if this code is
  44     reached (in debug mode).
  45
  46     This macro is useful for marking unreachable" code areas, for example
  47     it may be used in the "default:" branch of a switch statement if all possible
  48     cases are processed above.
  49
  50     @sa wxFAIL
  51 */
  52 #define wxFAIL_MSG(msg)     /* implementation is private */
  53
  54 /**
  55     Checks that the condition is @true, returns with the given return value if not
  56     (FAILs in debug mode).
  57     This check is done even in release mode.
  58 */
  59 #define wxCHECK(condition,  retValue)     /* implementation is private */
  60
  61 /**
  62     This macro results in a
  63     @ref overview_wxcompiletimeassert "compile time assertion failure" if the size
  64     of the given type @e type is less than @e size bits.
  65
  66     You may use it like this, for example:
  67     @code
  68     // we rely on the int being able to hold values up to 2^32
  69         wxASSERT_MIN_BITSIZE(int, 32);
  70
  71         // can't work with the platforms using UTF-8 for wchar_t
  72         wxASSERT_MIN_BITSIZE(wchar_t, 16);
  73     @endcode
  74 */
  75 #define wxASSERT_MIN_BITSIZE(type,  size)     /* implementation is private */
  76
  77 /**
  78     Assert macro with message. An error message will be generated if the condition
  79     is @false.
  80
  81     @sa wxASSERT, wxCOMPILE_TIME_ASSERT
  82 */
  83 #define wxASSERT_MSG(condition,  msg)     /* implementation is private */
  84
  85 /**
  86     This is the same as wxCHECK2, but
  87     wxFAIL_MSG with the specified @e msg is called
  88     instead of wxFAIL() if the @e condition is @false.
  89 */
  90 #define wxCHECK2(condition,  operation,  msg)     /* implementation is private */
  91
  92 /**
  93     Assert macro. An error message will be generated if the condition is @false in
  94     debug mode, but nothing will be done in the release build.
  95
  96     Please note that the condition in wxASSERT() should have no side effects
  97     because it will not be executed in release mode at all.
  98
  99     @sa wxASSERT_MSG, wxCOMPILE_TIME_ASSERT
 100 */
 101 #define wxASSERT(condition)     /* implementation is private */
 102
 103 /**
 104     Checks that the condition is @true, and returns if not (FAILs with given error
 105     message in debug mode). This check is done even in release mode.
 106
 107     This macro should be used in void functions instead of
 108     wxCHECK_MSG.
 109 */
 110 #define wxCHECK_RET(condition,  msg)     /* implementation is private */
 111
 112 /**
 113     Checks that the condition is @true and wxFAIL and execute
 114     @e operation if it is not. This is a generalisation of
 115     wxCHECK and may be used when something else than just
 116     returning from the function must be done when the @e condition is @false.
 117
 118     This check is done even in release mode.
 119 */
 120 #define wxCHECK2(condition,  operation)     /* implementation is private */
 121
 122 /**
 123     This macro is identical to wxCOMPILE_TIME_ASSERT2
 124     except that it allows you to specify a unique @e name for the struct
 125     internally defined by this macro to avoid getting the compilation errors
 126     described above.
 127 */
 128 #define wxCOMPILE_TIME_ASSERT(condition,  msg,  name)     /* implementation is private */
 129
 130 /**
 131     Checks that the condition is @true, returns with the given return value if not
 132     (FAILs in debug mode).
 133     This check is done even in release mode.
 134
 135     This macro may be only used in non-void functions, see also
 136     wxCHECK_RET.
 137 */
 138 #define wxCHECK_MSG(condition,  retValue,  msg)     /* implementation is private */
 139
 140 /**
 141     Using @c wxCOMPILE_TIME_ASSERT results in a compilation error if the
 142     specified @e condition is @false. The compiler error message should include
 143     the @e msg identifier - please note that it must be a valid C++ identifier
 144     and not a string unlike in the other cases.
 145
 146     This macro is mostly useful for testing the expressions involving the
 147     @c sizeof operator as they can't be tested by the preprocessor but it is
 148     sometimes desirable to test them at the compile time.
 149
 150     Note that this macro internally declares a struct whose name it tries to make
 151     unique by using the @c __LINE__ in it but it may still not work if you
 152     use it on the same line in two different source files. In this case you may
 153     either change the line in which either of them appears on or use the
 154     wxCOMPILE_TIME_ASSERT2 macro.
 155
 156     Also note that Microsoft Visual C++ has a bug which results in compiler errors
 157     if you use this macro with 'Program Database For Edit And Continue'
 158     (@c /ZI) option, so you shouldn't use it ('Program Database'
 159     (@c /Zi) is ok though) for the code making use of this macro.
 160
 161     @sa wxASSERT_MSG, wxASSERT_MIN_BITSIZE
 162 */
 163 #define wxCOMPILE_TIME_ASSERT(condition,  msg)     /* implementation is private */
 164