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