]>
git.saurik.com Git - wxWidgets.git/blob - include/wx/debug.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Misc debug functions and macros
4 // Author: Vadim Zeitlin
8 // Copyright: (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
16 #include <limits.h> // for CHAR_BIT used below
18 #include "wx/wxchar.h" // for __TFILE__ and wxChar
20 // ----------------------------------------------------------------------------
21 // Defines controlling the debugging macros
22 // ----------------------------------------------------------------------------
24 // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
29 #endif // !__WXDEBUG__
32 // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
38 // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
40 #if !defined(WXDEBUG) || !WXDEBUG
46 // ----------------------------------------------------------------------------
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.
56 // Warning: if you don't like advices on programming style, don't read
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 // ----------------------------------------------------------------------------
66 // Macros which are completely disabled in 'release' mode
68 // NB: these functions are implemented in src/common/appcmn.cpp
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
76 szFile and nLine - file name and line number of the ASSERT
77 szMsg - optional message explaining the reason
79 extern void WXDLLEXPORT
wxOnAssert(const wxChar
*szFile
,
81 const wxChar
*szMsg
= NULL
);
83 // call this function to break into the debugger uncodnitionally (assuming
84 // the program is running under debugger, of course)
85 extern void WXDLLEXPORT
wxTrap();
88 notice the usage of else at the end of wxASSERT macro: this ensures that
96 works like expected: if there were no "else", the one in the code above
97 would be matched with a wrong "if"
100 // generic assert macro
101 #define wxASSERT(cond) if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__); else
103 // assert with additional message explaining it's cause
104 #define wxASSERT_MSG(cond, msg) \
105 if ( !(cond) ) wxOnAssert(__TFILE__, __LINE__, msg); else
107 // an assert helper used to avoid warning when testing constant expressions,
108 // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
109 // expression being always true, but not using
110 // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
111 extern bool WXDLLEXPORT
wxAssertIsEqual(int x
, int y
);
115 // nothing to do in release modes (hopefully at this moment there are
117 #define wxASSERT(cond)
118 #define wxASSERT_MSG(x, m)
121 // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
122 // constant expression
123 WXDLLEXPORT_DATA(extern const bool) wxFalse
;
125 // special form of assert: always triggers it (in debug mode)
126 #define wxFAIL wxASSERT(wxFalse)
128 // FAIL with some message
129 #define wxFAIL_MSG(msg) wxASSERT_MSG(wxFalse, msg)
131 // NB: the following macros work also in release mode!
134 These macros must be used only in invalid situation: for example, an
135 invalid parameter (NULL pointer) is passed to a function. Instead of
136 dereferencing it and causing core dump the function might try using
137 CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
140 // check that expression is true, "return" if not (also FAILs in debug mode)
141 #define wxCHECK(x, rc) if (!(x)) {wxFAIL; return rc; }
143 // as wxCHECK but with a message explaining why we fail
144 #define wxCHECK_MSG(x, rc, msg) if (!(x)) {wxFAIL_MSG(msg); return rc; }
146 // check that expression is true, perform op if not
147 #define wxCHECK2(x, op) if (!(x)) {wxFAIL; op; }
149 // as wxCHECK2 but with a message explaining why we fail
150 #define wxCHECK2_MSG(x, op, msg) if (!(x)) {wxFAIL_MSG(msg); op; }
152 // special form of wxCHECK2: as wxCHECK, but for use in void functions
154 // NB: there is only one form (with msg parameter) and it's intentional:
155 // there is no other way to tell the caller what exactly went wrong
156 // from the void function (of course, the function shouldn't be void
158 #define wxCHECK_RET(x, msg) if (!(x)) {wxFAIL_MSG(msg); return; }
160 // ----------------------------------------------------------------------------
161 // Compile time asserts
163 // Unlike the normal assert and related macros above which are checked during
164 // the program tun-time the macros below will result in a compilation error if
165 // the condition they check is false. This is usually used to check the
166 // expressions containing sizeof()s which cannot be tested with the
167 // preprocessor. If you can use the #if's, do use them as you can give a more
168 // detailed error message then.
169 // ----------------------------------------------------------------------------
172 How this works (you don't have to understand it to be able to use the
173 macros): we rely on the fact that it is invalid to define a named bit field
174 in a struct of width 0. All the rest are just the hacks to minimize the
175 possibility of the compiler warnings when compiling this macro: in
176 particular, this is why we define a struct and not an object (which would
177 result in a warning about unused variable) and a named struct (otherwise we'd
178 get a warning about an unnamed struct not used to define an object!).
181 #define wxMAKE_ASSERT_NAME_HELPER(line) wxAssert_ ## line
182 #define wxMAKE_ASSERT_NAME(line) wxMAKE_ASSERT_NAME_HELPER(line)
183 #define wxMAKE_UNIQUE_ASSERT_NAME wxMAKE_ASSERT_NAME(__LINE__)
186 The second argument of this macro must be a valid C++ identifier and not a
187 string. I.e. you should use it like this:
189 wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
191 It may be used both within a function and in the global scope.
193 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
194 struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
196 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
197 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
199 // a special case of compile time assert: check that the size of the given type
200 // is at least the given number of bits
201 #define wxASSERT_MIN_BITSIZE(type, size) \
202 wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
203 wxMAKE_BITSIZE_MSG(type, size))
205 #endif // _WX_DEBUG_H_