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   void WXDLLEXPORT wxOnAssert(const wxChar *szFile, int nLine, const wxChar *szMsg = (const wxChar *) NULL);
  55
  56   /*
  57     notice the usage of else at the end of wxASSERT macro: this ensures that
  58     the following code
  59
  60         if ( ... )
  61             wxASSERT(...);
  62         else
  63             ...
  64
  65     works like expected: if there were no "else", the one in the code above
  66     would be matched with a wrong "if"
  67   */
  68
  69   // generic assert macro
  70   #define wxASSERT(cond) if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__); else
  71
  72   // assert with additional message explaining it's cause
  73   #define wxASSERT_MSG(cond, msg) \
  74                     if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__, msg); else
  75 #else
  76   // nothing to do in release modes (hopefully at this moment there are
  77   // no more bugs ;-)
  78   #define wxASSERT(cond)
  79   #define wxASSERT_MSG(x, m)
  80 #endif  //__WXDEBUG__
  81
  82 // special form of assert: always triggers it (in debug mode)
  83 #define wxFAIL                 wxASSERT(wxFalse)
  84
  85 // FAIL with some message
  86 #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxFalse, msg)
  87
  88 // NB: the following macros work also in release mode!
  89
  90 /*
  91   These macros must be used only in invalid situation: for example, an
  92   invalid parameter (NULL pointer) is passed to a function. Instead of
  93   dereferencing it and causing core dump the function might try using
  94   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
  95 */
  96
  97 // check that expression is true, "return" if not (also FAILs in debug mode)
  98 #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
  99
 100 // as wxCHECK but with a message explaining why we fail
 101 #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 102
 103 // check that expression is true, perform op if not
 104 #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 105
 106 // as wxCHECK2 but with a message explaining why we fail
 107 #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 108
 109 // special form of wxCHECK2: as wxCHECK, but for use in void functions
 110 //  NB: there is only one form (with msg parameter) and it's intentional:
 111 //      there is no other way to tell the caller what exactly went wrong
 112 //      from the void function (of course, the function shouldn't be void
 113 //      to begin with...)
 114 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 115
 116 #endif  // _WX_DEBUG_H_
 117