home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / wxos2240.zip / wxWindows-2.4.0 / include / wx / debug.h < prev    next >
C/C++ Source or Header  |  2002-12-09  |  9KB  |  221 lines
  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: debug.h,v 1.21.2.4 2002/12/09 14:35:09 JS Exp $
  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. #include  <limits.h>            // for CHAR_BIT used below
  17.  
  18. #include  "wx/wxchar.h"         // for __TFILE__ and wxChar
  19.  
  20. // ----------------------------------------------------------------------------
  21. // Defines controlling the debugging macros
  22. // ----------------------------------------------------------------------------
  23.  
  24. // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
  25. // __WXDEBUG__ too
  26. #ifdef _DEBUG
  27.     #ifndef __WXDEBUG__
  28.         #define __WXDEBUG__
  29.     #endif // !__WXDEBUG__
  30. #endif // _DEBUG
  31.  
  32. // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
  33. #ifdef NDEBUG
  34.     #undef __WXDEBUG__
  35.     #undef WXDEBUG
  36. #endif // NDEBUG
  37.  
  38. // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
  39. #ifdef __WXDEBUG__
  40.     #if !defined(WXDEBUG) || !WXDEBUG
  41.         #undef WXDEBUG
  42.         #define WXDEBUG 1
  43.     #endif // !WXDEBUG
  44. #endif // __WXDEBUG__
  45.  
  46. // ----------------------------------------------------------------------------
  47. // Debugging macros
  48. //
  49. // All debugging macros rely on ASSERT() which in turn calls user-defined
  50. // OnAssert() function. To keep things simple, it's called even when the
  51. // expression is TRUE (i.e. everything is ok) and by default does nothing: just
  52. // returns the same value back. But if you redefine it to do something more sexy
  53. // (popping up a message box in your favourite GUI, sending you e-mail or
  54. // whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
  55. //
  56. // Warning: if you don't like advices on programming style, don't read
  57. // further! ;-)
  58. //
  59. // Extensive use of these macros is recommended! Remember that ASSERTs are
  60. // disabled in final (without __WXDEBUG__ defined) build, so they add strictly
  61. // nothing to your program's code. On the other hand, CHECK macros do stay
  62. // even in release builds, but in general are not much of a burden, while
  63. // a judicious use of them might increase your program's stability.
  64. // ----------------------------------------------------------------------------
  65.  
  66. // Macros which are completely disabled in 'release' mode
  67. //
  68. // NB: these functions are implemented in src/common/appcmn.cpp
  69. #ifdef  __WXDEBUG__
  70.   /*
  71.     this function may be redefined to do something non trivial and is called
  72.     whenever one of debugging macros fails (i.e. condition is false in an
  73.     assertion)
  74.  
  75.     parameters:
  76.        szFile and nLine - file name and line number of the ASSERT
  77.        szMsg            - optional message explaining the reason
  78.   */
  79.   extern void WXDLLEXPORT wxOnAssert(const wxChar *szFile,
  80.                                      int nLine,
  81.                                      const wxChar *szCond,
  82.                                      const wxChar *szMsg = NULL);
  83.  
  84.   // call this function to break into the debugger uncodnitionally (assuming
  85.   // the program is running under debugger, of course)
  86.   extern void WXDLLEXPORT wxTrap();
  87.  
  88.   // helper function used to implement wxASSERT and wxASSERT_MSG
  89.   //
  90.   // note using "int" and not "bool" for cond to avoid VC++ warnings about
  91.   // implicit conversions when doing "wxAssert( pointer )" and also use of
  92.   // "!!cond" below to ensure that everything is converted to int
  93.   extern void WXDLLEXPORT wxAssert(int cond,
  94.                                    const wxChar *szFile,
  95.                                    int nLine,
  96.                                    const wxChar *szCond,
  97.                                    const wxChar *szMsg = NULL) ;
  98.  
  99.   // generic assert macro
  100.   #define wxASSERT(cond) wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond))
  101.  
  102.   // assert with additional message explaining it's cause
  103.   #define wxASSERT_MSG(cond, msg) \
  104.     wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond), msg)
  105.  
  106.   // an assert helper used to avoid warning when testing constant expressions,
  107.   // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
  108.   // expression being always true, but not using
  109.   // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
  110.   //
  111.   // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and shouldn't be
  112.   //     used any longer
  113.   extern bool WXDLLEXPORT wxAssertIsEqual(int x, int y);
  114. #else
  115.   #define wxTrap()
  116.  
  117.   // nothing to do in release modes (hopefully at this moment there are
  118.   // no more bugs ;-)
  119.   #define wxASSERT(cond)
  120.   #define wxASSERT_MSG(x, m)
  121. #endif  //__WXDEBUG__
  122.  
  123. // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
  124. // constant expression
  125. WXDLLEXPORT_DATA(extern const bool) wxFalse;
  126. #define wxAssertFailure wxFalse
  127.  
  128. // special form of assert: always triggers it (in debug mode)
  129. #define wxFAIL                 wxASSERT(wxAssertFailure)
  130.  
  131. // FAIL with some message
  132. #define wxFAIL_MSG(msg)        wxASSERT_MSG(wxAssertFailure, msg)
  133.  
  134. // NB: the following macros work also in release mode!
  135.  
  136. /*
  137.   These macros must be used only in invalid situation: for example, an
  138.   invalid parameter (NULL pointer) is passed to a function. Instead of
  139.   dereferencing it and causing core dump the function might try using
  140.   CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
  141. */
  142.  
  143. // check that expression is true, "return" if not (also FAILs in debug mode)
  144. #define wxCHECK(x, rc)            if (!(x)) {wxFAIL; return rc; }
  145.  
  146. // as wxCHECK but with a message explaining why we fail
  147. #define wxCHECK_MSG(x, rc, msg)   if (!(x)) {wxFAIL_MSG(msg); return rc; }
  148.  
  149. // check that expression is true, perform op if not
  150. #define wxCHECK2(x, op)           if (!(x)) {wxFAIL; op; }
  151.  
  152. // as wxCHECK2 but with a message explaining why we fail
  153. #define wxCHECK2_MSG(x, op, msg)  if (!(x)) {wxFAIL_MSG(msg); op; }
  154.  
  155. // special form of wxCHECK2: as wxCHECK, but for use in void functions
  156. //
  157. // NB: there is only one form (with msg parameter) and it's intentional:
  158. //     there is no other way to tell the caller what exactly went wrong
  159. //     from the void function (of course, the function shouldn't be void
  160. //     to begin with...)
  161. #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
  162.  
  163. // ----------------------------------------------------------------------------
  164. // Compile time asserts
  165. //
  166. // Unlike the normal assert and related macros above which are checked during
  167. // the program tun-time the macros below will result in a compilation error if
  168. // the condition they check is false. This is usually used to check the
  169. // expressions containing sizeof()s which cannot be tested with the
  170. // preprocessor. If you can use the #if's, do use them as you can give a more
  171. // detailed error message then.
  172. // ----------------------------------------------------------------------------
  173.  
  174. /*
  175.   How this works (you don't have to understand it to be able to use the
  176.   macros): we rely on the fact that it is invalid to define a named bit field
  177.   in a struct of width 0. All the rest are just the hacks to minimize the
  178.   possibility of the compiler warnings when compiling this macro: in
  179.   particular, this is why we define a struct and not an object (which would
  180.   result in a warning about unused variable) and a named struct (otherwise we'd
  181.   get a warning about an unnamed struct not used to define an object!).
  182.   The _n__ part is to stop VC++ 7 being confused since it encloses __LINE++ in
  183.   parentheses. Unfortunately this does not work with other compilers, so
  184.   we will only enable it when we know the _precise_ symbols to test for.
  185.  */
  186.  
  187. #define wxMAKE_ASSERT_NAME_HELPER(line)     wxAssert_ ## line
  188. #define wxMAKE_ASSERT_NAME(line)            wxMAKE_ASSERT_NAME_HELPER(line)
  189. #if 0
  190. #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_ASSERT_NAME(_n___ ## __LINE__)
  191. #else
  192. #define wxMAKE_UNIQUE_ASSERT_NAME           wxMAKE_ASSERT_NAME(__LINE__)
  193. #endif
  194. #define wxMAKE_UNIQUE_ASSERT_NAME2(text)    wxMAKE_ASSERT_NAME(text)
  195.  
  196. /*
  197.   The second argument of this macro must be a valid C++ identifier and not a
  198.   string. I.e. you should use it like this:
  199.  
  200.     wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
  201.  
  202.  It may be used both within a function and in the global scope.
  203. */
  204. #define wxCOMPILE_TIME_ASSERT(expr, msg) \
  205.     struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
  206.  
  207. #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
  208.     struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
  209.  
  210. // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
  211. #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
  212.  
  213. // a special case of compile time assert: check that the size of the given type
  214. // is at least the given number of bits
  215. #define wxASSERT_MIN_BITSIZE(type, size) \
  216.     wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
  217.                           wxMAKE_BITSIZE_MSG(type, size))
  218.  
  219. #endif  // _WX_DEBUG_H_
  220.  
  221.