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
  17 #include  "wx/wxchar.h"
  18
  19 // ----------------------------------------------------------------------------
  20 // Defines controlling the debugging macros
  21 // ----------------------------------------------------------------------------
  22
  23 // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
  24 // __WXDEBUG__ too
  25 #ifdef _DEBUG
  26     #ifndef __WXDEBUG__
  27         #define __WXDEBUG__
  28     #endif // !__WXDEBUG__
  29 #endif // _DEBUG
  30
  31 // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
  32 #ifdef NDEBUG
  33     #undef __WXDEBUG__
  34     #undef WXDEBUG
  35 #endif // NDEBUG
  36
  37 // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
  38 #ifdef __WXDEBUG__
  39     #if !defined(WXDEBUG) || !WXDEBUG
  40         #undef WXDEBUG
  41         #define WXDEBUG 1
  42     #endif // !WXDEBUG
  43 #endif // __WXDEBUG__
  44
  45 // ----------------------------------------------------------------------------
  46 // Debugging macros
  47 //
  48 // All debugging macros rely on ASSERT() which in turn calls user-defined
  49 // OnAssert() function. To keep things simple, it's called even when the
  50 // expression is TRUE (i.e. everything is ok) and by default does nothing: just
  51 // returns the same value back. But if you redefine it to do something more sexy
  52 // (popping up a message box in your favourite GUI, sending you e-mail or
  53 // whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  54 //
  55 // Warning: if you don't like advices on programming style, don't read
  56 // further! ;-)
  57 //
  58 // Extensive use of these macros is recommended! Remember that ASSERTs are
  59 // disabled in final (without __WXDEBUG__ defined) build, so they add strictly
  60 // nothing to your program's code. On the other hand, CHECK macros do stay
  61 // even in release builds, but in general are not much of a burden, while
  62 // a judicious use of them might increase your program's stability.
  63 // ----------------------------------------------------------------------------
  64
  65 // Macros which are completely disabled in 'release' mode
  66 //
  67 // NB: these functions are implemented in src/common/appcmn.cpp
  68 #ifdef  __WXDEBUG__
  69   /*
  70     this function may be redefined to do something non trivial and is called
  71     whenever one of debugging macros fails (i.e. condition is false in an
  72     assertion)
  73
  74     parameters:
  75        szFile and nLine - file name and line number of the ASSERT
  76        szMsg            - optional message explaining the reason
  77   */
  78   extern void WXDLLEXPORT wxOnAssert(const wxChar *szFile,
  79                                      int nLine,
  80                                      const wxChar *szMsg = NULL);
  81
  82   // call this function to break into the debugger uncodnitionally (assuming
  83   // the program is running under debugger, of course)
  84   extern void WXDLLEXPORT wxTrap();
  85
  86   /*
  87     notice the usage of else at the end of wxASSERT macro: this ensures that
  88     the following code
  89
  90         if ( ... )
  91             wxASSERT(...);
  92         else
  93             ...
  94
  95     works like expected: if there were no "else", the one in the code above
  96     would be matched with a wrong "if"
  97   */
  98
  99   // generic assert macro
 100   #define wxASSERT(cond) if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__); else
 101
 102   // assert with additional message explaining it's cause
 103   #define wxASSERT_MSG(cond, msg) \
 104                     if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__, msg); else
 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   extern bool WXDLLEXPORT wxAssertIsEqual(int x, int y);
 111 #else
 112   #define wxTrap()
 113
 114   // nothing to do in release modes (hopefully at this moment there are
 115   // no more bugs ;-)
 116   #define wxASSERT(cond)
 117   #define wxASSERT_MSG(x, m)
 118 #endif  //__WXDEBUG__
 119
 120 // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
 121 // constant expression
 122 WXDLLEXPORT_DATA(extern const bool) wxFalse;
 123
 124 // special form of assert: always triggers it (in debug mode)
 125 #define wxFAIL                 wxASSERT(wxFalse)
 126
 127 // FAIL with some message
 128 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxFalse, msg)
 129
 130 // NB: the following macros work also in release mode!
 131
 132 /*
 133   These macros must be used only in invalid situation: for example, an
 134   invalid parameter (NULL pointer) is passed to a function. Instead of
 135   dereferencing it and causing core dump the function might try using
 136   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 137 */
 138
 139 // check that expression is true, "return" if not (also FAILs in debug mode)
 140 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 141
 142 // as wxCHECK but with a message explaining why we fail
 143 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 144
 145 // check that expression is true, perform op if not
 146 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 147
 148 // as wxCHECK2 but with a message explaining why we fail
 149 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 150
 151 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 152 //
 153 // NB: there is only one form (with msg parameter) and it's intentional:
 154 //     there is no other way to tell the caller what exactly went wrong
 155 //     from the void function (of course, the function shouldn't be void
 156 //     to begin with...)
 157 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 158
 159 #endif  // _WX_DEBUG_H_
 160