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   __DEBUGH__
  13 #define   __DEBUGH__
  14
  15 #include  <assert.h>
  16
  17 // ----------------------------------------------------------------------------
  18 /**
  19   @name Debugging macros
  20
  21   All debugging macros rely on ASSERT() which in turn calls user-defined
  22   OnAssert() function. To keep things simple, it's called even when the
  23   expression is TRUE (i.e. everything is ok) and by default does nothing: just
  24   returns the same value back. But if you redefine it to do something more sexy
  25   (popping up a message box in your favourite GUI, sending you e-mail or
  26   whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  27   <BR>
  28   <BR>
  29   <b>Warning</b>: if you don't like advices on programming style, don't read
  30   further! ;-)
  31   <BR>
  32   <BR>
  33   Extensive use of these macros is recommended! Remember that ASSERTs are
  34   disabled in final (without DEBUG defined) build, so they add strictly
  35   nothing to your program's code. On the other hand, CHECK macros do stay
  36   even in release builds, but in general are not much of a burden, while
  37   a judicious use of them might increase your program's stability.
  38
  39   @memo Debugging macros (replacement for standard assert()) and more.
  40   */
  41 // ----------------------------------------------------------------------------
  42 //@{
  43
  44 /** @name Macros which are completely disabled in 'release' mode */
  45 //@{
  46 #ifdef  __DEBUG__
  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   @param   szFile and nLine - file name and line number of the ASSERT
  52            szMsg            - optional message explaining the reason
  53   */
  54   void wxOnAssert(const char *szFile, int nLine, const char *szMsg = NULL);
  55
  56   /// generic assert macro
  57   #define   wxASSERT(cond)   if ( !(cond) ) wxOnAssert(__FILE__, __LINE__)
  58   /// assert with additional message explaining it's cause
  59   #define   wxASSERT_MSG(x, m)  if ( !(x) ) wxOnAssert(__FILE__, __LINE__, m)
  60 #else
  61   // nothing to do in release modes (hopefully at this moment there are
  62   // no more bugs ;-)
  63   #define   wxASSERT(cond)
  64   #define   wxASSERT_MSG(x, m)
  65 #endif  //DEBUG
  66
  67   /// special form of assert: always triggers it (in debug mode)
  68 #define   wxFAIL                 wxASSERT(0)
  69   /// FAIL with some message
  70 #define   wxFAIL_MSG(msg)        wxASSERT_MSG(0, msg)
  71 //@}
  72
  73 // NB: these macros work also in release mode!
  74
  75 /**
  76   These macros must be used only in invalid situation: for example, an
  77   invalid parameter (NULL pointer) is passed to a function. Instead of
  78   dereferencing it and causing core dump the function might try using
  79   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
  80
  81   @name Macros which remain even in 'release' mode
  82 */
  83 //@{
  84   /// check that expression is true, "return" if not (also FAILs in debug mode)
  85 #define   wxCHECK(x)             if (!(x)) {wxFAIL; return; }
  86   /// check that expression is true, "return ret" if not
  87 #define   wxCHECK_RET(x, ret)    if (!(x)) {wxFAIL; return ret; }
  88   /// check that expression is true, perform op if not
  89 #define   wxCHECK2(x, op)        if (!(x)) {wxFAIL; op; }
  90 //@}
  91
  92 //@}
  93
  94 #endif  // __DEBUGH__
  95