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   inline void WXDLLEXPORT wxAssert(int cond,
  94                                    const wxChar *szFile,
  95                                    int nLine,
  96                                    const wxChar *szCond,
  97                                    const wxChar *szMsg = NULL)
  98   {
  99       if ( !cond )
 100           wxOnAssert(szFile, nLine, szCond, szMsg);
 101   }
 102
 103   // generic assert macro
 104   #define wxASSERT(cond) wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond))
 105
 106   // assert with additional message explaining it's cause
 107   #define wxASSERT_MSG(cond, msg) \
 108     wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond), msg)
 109
 110   // an assert helper used to avoid warning when testing constant expressions,
 111   // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
 112   // expression being always true, but not using
 113   // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
 114   //
 115   // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and shouldn't be
 116   //     used any longer
 117   extern bool WXDLLEXPORT wxAssertIsEqual(int x, int y);
 118 #else
 119   #define wxTrap()
 120
 121   // nothing to do in release modes (hopefully at this moment there are
 122   // no more bugs ;-)
 123   #define wxASSERT(cond)
 124   #define wxASSERT_MSG(x, m)
 125 #endif  //__WXDEBUG__
 126
 127 // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
 128 // constant expression
 129 WXDLLEXPORT_DATA(extern const bool) wxFalse;
 130
 131 // special form of assert: always triggers it (in debug mode)
 132 #define wxFAIL                 wxASSERT(wxFalse)
 133
 134 // FAIL with some message
 135 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxFalse, msg)
 136
 137 // NB: the following macros work also in release mode!
 138
 139 /*
 140   These macros must be used only in invalid situation: for example, an
 141   invalid parameter (NULL pointer) is passed to a function. Instead of
 142   dereferencing it and causing core dump the function might try using
 143   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 144 */
 145
 146 // check that expression is true, "return" if not (also FAILs in debug mode)
 147 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 148
 149 // as wxCHECK but with a message explaining why we fail
 150 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 151
 152 // check that expression is true, perform op if not
 153 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 154
 155 // as wxCHECK2 but with a message explaining why we fail
 156 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 157
 158 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 159 //
 160 // NB: there is only one form (with msg parameter) and it's intentional:
 161 //     there is no other way to tell the caller what exactly went wrong
 162 //     from the void function (of course, the function shouldn't be void
 163 //     to begin with...)
 164 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 165
 166 // ----------------------------------------------------------------------------
 167 // Compile time asserts
 168 //
 169 // Unlike the normal assert and related macros above which are checked during
 170 // the program tun-time the macros below will result in a compilation error if
 171 // the condition they check is false. This is usually used to check the
 172 // expressions containing sizeof()s which cannot be tested with the
 173 // preprocessor. If you can use the #if's, do use them as you can give a more
 174 // detailed error message then.
 175 // ----------------------------------------------------------------------------
 176
 177 /*
 178   How this works (you don't have to understand it to be able to use the
 179   macros): we rely on the fact that it is invalid to define a named bit field
 180   in a struct of width 0. All the rest are just the hacks to minimize the
 181   possibility of the compiler warnings when compiling this macro: in
 182   particular, this is why we define a struct and not an object (which would
 183   result in a warning about unused variable) and a named struct (otherwise we'd
 184   get a warning about an unnamed struct not used to define an object!).
 185  */
 186
 187 #define wxMAKE_ASSERT_NAME_HELPER(line)     wxAssert_ ## line
 188 #define wxMAKE_ASSERT_NAME(line)            wxMAKE_ASSERT_NAME_HELPER(line)
 189 #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_ASSERT_NAME(__LINE__)
 190 #define wxMAKE_UNIQUE_ASSERT_NAME2(text)    wxMAKE_ASSERT_NAME(text)
 191
 192 /*
 193   The second argument of this macro must be a valid C++ identifier and not a
 194   string. I.e. you should use it like this:
 195
 196     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
 197
 198  It may be used both within a function and in the global scope.
 199 */
 200 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
 201     struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
 202
 203 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
 204     struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
 205
 206 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
 207 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
 208
 209 // a special case of compile time assert: check that the size of the given type
 210 // is at least the given number of bits
 211 #define wxASSERT_MIN_BITSIZE(type, size) \
 212     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
 213                           wxMAKE_BITSIZE_MSG(type, size))
 214
 215 #endif  // _WX_DEBUG_H_
 216