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 #ifdef  __WXDEBUG__
  45   /*
  46     this function may be redefined to do something non trivial and is called
  47     whenever one of debugging macros fails (i.e. condition is false in an
  48     assertion)
  49
  50     parameters:
  51        szFile and nLine - file name and line number of the ASSERT
  52        szMsg            - optional message explaining the reason
  53   */
  54   extern void WXDLLEXPORT wxOnAssert(const wxChar *szFile,
  55                                      int nLine,
  56                                      const wxChar *szMsg = NULL);
  57
  58   // call this function to break into the debugger uncodnitionally (assuming
  59   // the program is running under debugger, of course)
  60   extern void WXDLLEXPORT wxTrap();
  61
  62   /*
  63     notice the usage of else at the end of wxASSERT macro: this ensures that
  64     the following code
  65
  66         if ( ... )
  67             wxASSERT(...);
  68         else
  69             ...
  70
  71     works like expected: if there were no "else", the one in the code above
  72     would be matched with a wrong "if"
  73   */
  74
  75   // generic assert macro
  76   #define wxASSERT(cond) if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__); else
  77
  78   // assert with additional message explaining it's cause
  79   #define wxASSERT_MSG(cond, msg) \
  80                     if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__, msg); else
  81
  82   // an assert helper used to avoid warning when testing constant expressions,
  83   // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
  84   // expression being always true, but not using
  85   // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
  86   extern bool WXDLLEXPORT wxAssertIsEqual(int x, int y);
  87 #else
  88   #define wxTrap()
  89
  90   // nothing to do in release modes (hopefully at this moment there are
  91   // no more bugs ;-)
  92   #define wxASSERT(cond)
  93   #define wxASSERT_MSG(x, m)
  94 #endif  //__WXDEBUG__
  95
  96 // special form of assert: always triggers it (in debug mode)
  97 #define wxFAIL                 wxASSERT(wxFalse)
  98
  99 // FAIL with some message
 100 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxFalse, msg)
 101
 102 // NB: the following macros work also in release mode!
 103
 104 /*
 105   These macros must be used only in invalid situation: for example, an
 106   invalid parameter (NULL pointer) is passed to a function. Instead of
 107   dereferencing it and causing core dump the function might try using
 108   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 109 */
 110
 111 // check that expression is true, "return" if not (also FAILs in debug mode)
 112 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 113
 114 // as wxCHECK but with a message explaining why we fail
 115 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 116
 117 // check that expression is true, perform op if not
 118 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 119
 120 // as wxCHECK2 but with a message explaining why we fail
 121 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 122
 123 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 124 //
 125 // NB: there is only one form (with msg parameter) and it's intentional:
 126 //     there is no other way to tell the caller what exactly went wrong
 127 //     from the void function (of course, the function shouldn't be void
 128 //     to begin with...)
 129 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 130
 131 #endif  // _WX_DEBUG_H_
 132