include/wx/debug.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        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 #ifndef __TFILE__
  20 #define __XFILE__(x) _T(x)
  21 #define __TFILE__ __XFILE__(__FILE__)
  22 #endif
  23
  24 // ----------------------------------------------------------------------------
  25 /**
  26   @name Debugging macros
  27
  28   All debugging macros rely on ASSERT() which in turn calls user-defined
  29   OnAssert() function. To keep things simple, it's called even when the
  30   expression is TRUE (i.e. everything is ok) and by default does nothing: just
  31   returns the same value back. But if you redefine it to do something more sexy
  32   (popping up a message box in your favourite GUI, sending you e-mail or
  33   whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  34   <BR>
  35   <BR>
  36   <b>Warning</b>: if you don't like advices on programming style, don't read
  37   further! ;-)
  38   <BR>
  39   <BR>
  40   Extensive use of these macros is recommended! Remember that ASSERTs are
  41   disabled in final (without __WXDEBUG__ defined) build, so they add strictly
  42   nothing to your program's code. On the other hand, CHECK macros do stay
  43   even in release builds, but in general are not much of a burden, while
  44   a judicious use of them might increase your program's stability.
  45
  46   @memo Debugging macros (replacement for standard assert()) and more.
  47   */
  48 // ----------------------------------------------------------------------------
  49 //@{
  50
  51 /** @name Macros which are completely disabled in 'release' mode */
  52 //@{
  53 #ifdef  __WXDEBUG__
  54   /**
  55   this function may be redefined to do something non trivial and is called
  56   whenever one of debugging macros fails (i.e. condition is false in an
  57   assertion)
  58   @param   szFile and nLine - file name and line number of the ASSERT
  59            szMsg            - optional message explaining the reason
  60   */
  61   void WXDLLEXPORT wxOnAssert(const wxChar *szFile, int nLine, const wxChar *szMsg = (const wxChar *) NULL);
  62
  63   /// generic assert macro
  64   #define   wxASSERT(cond)   if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__)
  65
  66 #if 0 // defined(__BORLANDC__) && defined(__WIN16__)
  67   // Too much text, so make wxASSERT_MSG the same as wxASSERT,
  68   // thus removing the text from the program.
  69   #define   wxASSERT_MSG(x, m)  if ( !(x) ) wxOnAssert(__TFILE__, __LINE__)
  70 #else
  71   /// assert with additional message explaining it's cause
  72   #define   wxASSERT_MSG(x, m)  if ( !(x) ) wxOnAssert(__TFILE__, __LINE__, m)
  73 #endif
  74
  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 #if 0 // defined(__BORLANDC__) && defined(__WIN16__)
  86   // Too much text, so make wxFAIL_MSG the same as wxFAIL,
  87   // thus removing the text from the program.
  88 #define   wxFAIL_MSG(msg)        wxASSERT(wxFalse)
  89 #else
  90   /// FAIL with some message
  91 #define   wxFAIL_MSG(msg)        wxASSERT_MSG(wxFalse, msg)
  92 #endif
  93 //@}
  94
  95 // NB: these macros work also in release mode!
  96
  97 /**
  98   These macros must be used only in invalid situation: for example, an
  99   invalid parameter (NULL pointer) is passed to a function. Instead of
 100   dereferencing it and causing core dump the function might try using
 101   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
 102
 103   @name Macros which remain even in 'release' mode
 104 */
 105 //@{
 106   /// check that expression is true, "return" if not (also FAILs in debug mode)
 107 #define   wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
 108   /// as wxCHECK but with a message explaining why we fail
 109 #define   wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
 110   /// check that expression is true, perform op if not
 111 #define   wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
 112   /// as wxCHECK2 but with a message explaining why we fail
 113 #define   wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
 114   /// special form of wxCHECK2: as wxCHECK, but for use in void functions
 115   //  NB: there is only one form (with msg parameter) and it's intentional:
 116   //      there is no other way to tell the caller what exactly went wrong
 117   //      from the void function (of course, the function shouldn't be void
 118   //      to begin with...)
 119 #define   wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 120 //@}
 121
 122 //@}
 123
 124 #endif  // _WX_DEBUG_H_