include/wx/debug.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/debug.h
   3 // Purpose:     Misc debug functions and macros
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     29/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef   _WX_DEBUG_H_
  13 #define   _WX_DEBUG_H_
  14
  15 #include  <assert.h>
  16 #include  <limits.h>            // for CHAR_BIT used below
  17
  18 #include  "wx/wxchar.h"         // for __TFILE__ and wxChar
  19
  20 // ----------------------------------------------------------------------------
  21 // Defines controlling the debugging macros
  22 // ----------------------------------------------------------------------------
  23
  24 // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
  25 // __WXDEBUG__ too
  26 #ifdef _DEBUG
  27     #ifndef __WXDEBUG__
  28         #define __WXDEBUG__
  29     #endif // !__WXDEBUG__
  30 #endif // _DEBUG
  31
  32 // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
  33 #ifdef NDEBUG
  34     #undef __WXDEBUG__
  35     #undef WXDEBUG
  36 #endif // NDEBUG
  37
  38 // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
  39 #ifdef __WXDEBUG__
  40     #if !defined(WXDEBUG) || !WXDEBUG
  41         #undef WXDEBUG
  42         #define WXDEBUG 1
  43     #endif // !WXDEBUG
  44 #endif // __WXDEBUG__
  45
  46 // ----------------------------------------------------------------------------
  47 // Debugging macros
  48 //
  49 // All debugging macros rely on ASSERT() which in turn calls user-defined
  50 // OnAssert() function. To keep things simple, it's called even when the
  51 // expression is TRUE (i.e. everything is ok) and by default does nothing: just
  52 // returns the same value back. But if you redefine it to do something more sexy
  53 // (popping up a message box in your favourite GUI, sending you e-mail or
  54 // whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  55 //
  56 // Warning: if you don't like advices on programming style, don't read
  57 // further! ;-)
  58 //
  59 // Extensive use of these macros is recommended! Remember that ASSERTs are
  60 // disabled in final (without __WXDEBUG__ defined) build, so they add strictly
  61 // nothing to your program's code. On the other hand, CHECK macros do stay
  62 // even in release builds, but in general are not much of a burden, while
  63 // a judicious use of them might increase your program's stability.
  64 // ----------------------------------------------------------------------------
  65
  66 // Macros which are completely disabled in 'release' mode
  67 //
  68 // NB: these functions are implemented in src/common/appcmn.cpp
  69 #ifdef  __WXDEBUG__
  70   /*
  71     this function may be redefined to do something non trivial and is called
  72     whenever one of debugging macros fails (i.e. condition is false in an
  73     assertion)
  74
  75     parameters:
  76        szFile and nLine - file name and line number of the ASSERT
  77        szMsg            - optional message explaining the reason
  78   */
  79   extern void WXDLLEXPORT wxOnAssert(const wxChar *szFile,
  80                                      int nLine,
  81                                      const wxChar *szCond,
  82                                      const wxChar *szMsg = NULL);
  83
  84   // call this function to break into the debugger uncodnitionally (assuming
  85   // the program is running under debugger, of course)
  86   extern void WXDLLEXPORT wxTrap();
  87
  88   // helper function used to implement wxASSERT and wxASSERT_MSG
  89   //
  90   // note using "int" and not "bool" for cond to avoid VC++ warnings about
  91   // implicit conversions when doing "wxAssert( pointer )" and also use of
  92   // "!!cond" below to ensure that everything is converted to int
  93   extern void WXDLLEXPORT wxAssert(int cond,
  94                                    const wxChar *szFile,
  95                                    int nLine,
  96                                    const wxChar *szCond,
  97                                    const wxChar *szMsg = NULL) ;
  98
  99   // generic assert macro
 100   #define wxASSERT(cond) wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond))
 101
 102   // assert with additional message explaining it's cause
 103   #define wxASSERT_MSG(cond, msg) \
 104     wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond), msg)
 105
 106   // an assert helper used to avoid warning when testing constant expressions,
 107   // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
 108   // expression being always true, but not using
 109   // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
 110   //
 111   // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and shouldn't be
 112   //     used any longer
 113   extern bool WXDLLEXPORT wxAssertIsEqual(int x, int y);
 114 #else
 115   #define wxTrap()
 116
 117   // nothing to do in release modes (hopefully at this moment there are
 118   // no more bugs ;-)
 119   #define wxASSERT(cond)
 120   #define wxASSERT_MSG(x, m)
 121 #endif  //__WXDEBUG__
 122
 123 // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
 124 // constant expression
 125 WXDLLEXPORT_DATA(extern const bool) wxFalse;
 126 #define wxAssertFailure wxFalse
 127
 128 // special form of assert: always triggers it (in debug mode)
 129 #define wxFAIL                 wxASSERT(wxAssertFailure)
 130
 131 // FAIL with some message
 132 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxAssertFailure, msg)
 133
 134 // NB: the following macros work also in release mode!
 135
 136 /*
 137   These macros must be used only in invalid situation: for example, an
 138   invalid parameter (NULL pointer) is passed to a function. Instead of
 139   dereferencing it and causing core dump the function might try using
 140   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 141 */
 142
 143 // check that expression is true, "return" if not (also FAILs in debug mode)
 144 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 145
 146 // as wxCHECK but with a message explaining why we fail
 147 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 148
 149 // check that expression is true, perform op if not
 150 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 151
 152 // as wxCHECK2 but with a message explaining why we fail
 153 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 154
 155 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 156 //
 157 // NB: there is only one form (with msg parameter) and it's intentional:
 158 //     there is no other way to tell the caller what exactly went wrong
 159 //     from the void function (of course, the function shouldn't be void
 160 //     to begin with...)
 161 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 162
 163 // ----------------------------------------------------------------------------
 164 // Compile time asserts
 165 //
 166 // Unlike the normal assert and related macros above which are checked during
 167 // the program tun-time the macros below will result in a compilation error if
 168 // the condition they check is false. This is usually used to check the
 169 // expressions containing sizeof()s which cannot be tested with the
 170 // preprocessor. If you can use the #if's, do use them as you can give a more
 171 // detailed error message then.
 172 // ----------------------------------------------------------------------------
 173
 174 /*
 175   How this works (you don't have to understand it to be able to use the
 176   macros): we rely on the fact that it is invalid to define a named bit field
 177   in a struct of width 0. All the rest are just the hacks to minimize the
 178   possibility of the compiler warnings when compiling this macro: in
 179   particular, this is why we define a struct and not an object (which would
 180   result in a warning about unused variable) and a named struct (otherwise we'd
 181   get a warning about an unnamed struct not used to define an object!).
 182   The _n__ part is to stop VC++ 7 being confused since it encloses __LINE++ in
 183   parentheses.
 184  */
 185
 186 #define wxMAKE_ASSERT_NAME_HELPER(line)     wxAssert_ ## line
 187 #define wxMAKE_ASSERT_NAME(line)            wxMAKE_ASSERT_NAME_HELPER(line)
 188 #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_ASSERT_NAME(_n___ ## __LINE__)
 189 #define wxMAKE_UNIQUE_ASSERT_NAME2(text)    wxMAKE_ASSERT_NAME(text)
 190
 191 /*
 192   The second argument of this macro must be a valid C++ identifier and not a
 193   string. I.e. you should use it like this:
 194
 195     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 196
 197  It may be used both within a function and in the global scope.
 198 */
 199 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 200     struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 201
 202 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
 203     struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
 204
 205 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 206 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 207
 208 // a special case of compile time assert: check that the size of the given type
 209 // is at least the given number of bits
 210 #define wxASSERT_MIN_BITSIZE(type, size) \
 211     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 212                           wxMAKE_BITSIZE_MSG(type, size))
 213
 214 #endif  // _WX_DEBUG_H_
 215