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