]>
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 /////////////////////////////////////////////////////////////////////////////
18 #include <limits.h> // for CHAR_BIT used below
20 #include "wx/wxchar.h" // for __TFILE__ and wxChar
22 // ----------------------------------------------------------------------------
23 // Defines controlling the debugging macros
24 // ----------------------------------------------------------------------------
26 // if _DEBUG is defined (MS VC++ and others use it in debug builds), define
31 #endif // !__WXDEBUG__
34 // if NDEBUG is defined (<assert.h> uses it), undef __WXDEBUG__ and WXDEBUG
40 // if __WXDEBUG__ is defined, make sure that WXDEBUG is defined and >= 1
42 #if !defined(WXDEBUG) || !WXDEBUG
48 // ----------------------------------------------------------------------------
51 // All debugging macros rely on ASSERT() which in turn calls user-defined
52 // OnAssert() function. To keep things simple, it's called even when the
53 // expression is TRUE (i.e. everything is ok) and by default does nothing: just
54 // returns the same value back. But if you redefine it to do something more sexy
55 // (popping up a message box in your favourite GUI, sending you e-mail or
56 // whatever) it will affect all ASSERTs, FAILs and CHECKs in your code.
58 // Warning: if you don't like advices on programming style, don't read
61 // Extensive use of these macros is recommended! Remember that ASSERTs are
62 // disabled in final (without __WXDEBUG__ defined) build, so they add strictly
63 // nothing to your program's code. On the other hand, CHECK macros do stay
64 // even in release builds, but in general are not much of a burden, while
65 // a judicious use of them might increase your program's stability.
66 // ----------------------------------------------------------------------------
68 // Macros which are completely disabled in 'release' mode
70 // NB: these functions are implemented in src/common/appcmn.cpp
73 this function may be redefined to do something non trivial and is called
74 whenever one of debugging macros fails (i.e. condition is false in an
78 szFile and nLine - file name and line number of the ASSERT
79 szMsg - optional message explaining the reason
81 extern void WXDLLEXPORT
wxOnAssert(const wxChar
*szFile
,
84 const wxChar
*szMsg
= NULL
);
86 // call this function to break into the debugger uncodnitionally (assuming
87 // the program is running under debugger, of course)
88 extern void WXDLLEXPORT
wxTrap();
90 // helper function used to implement wxASSERT and wxASSERT_MSG
92 // note using "int" and not "bool" for cond to avoid VC++ warnings about
93 // implicit conversions when doing "wxAssert( pointer )" and also use of
94 // "!!cond" below to ensure that everything is converted to int
95 extern void WXDLLEXPORT
wxAssert(int cond
,
99 const wxChar
*szMsg
= NULL
) ;
101 // generic assert macro
102 #define wxASSERT(cond) wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond))
104 // assert with additional message explaining it's cause
105 #define wxASSERT_MSG(cond, msg) \
106 wxAssert(!!(cond), __TFILE__, __LINE__, _T(#cond), msg)
108 // an assert helper used to avoid warning when testing constant expressions,
109 // i.e. wxASSERT( sizeof(int) == 4 ) can generate a compiler warning about
110 // expression being always true, but not using
111 // wxASSERT( wxAssertIsEqual(sizeof(int), 4) )
113 // NB: this is made obsolete by wxCOMPILE_TIME_ASSERT() and shouldn't be
115 extern bool WXDLLEXPORT
wxAssertIsEqual(int x
, int y
);
119 // nothing to do in release modes (hopefully at this moment there are
121 #define wxASSERT(cond)
122 #define wxASSERT_MSG(x, m)
125 // Use of wxFalse instead of FALSE suppresses compiler warnings about testing
126 // constant expression
127 WXDLLEXPORT_DATA(extern const bool) wxFalse
;
128 #define wxAssertFailure wxFalse
130 // special form of assert: always triggers it (in debug mode)
131 #define wxFAIL wxASSERT(wxAssertFailure)
133 // FAIL with some message
134 #define wxFAIL_MSG(msg) wxASSERT_MSG(wxAssertFailure, msg)
136 // NB: the following macros work also in release mode!
139 These macros must be used only in invalid situation: for example, an
140 invalid parameter (NULL pointer) is passed to a function. Instead of
141 dereferencing it and causing core dump the function might try using
142 CHECK( p != NULL ) or CHECK( p != NULL, return LogError("p is NULL!!") )
145 // check that expression is true, "return" if not (also FAILs in debug mode)
146 #define wxCHECK(x, rc) if (!(x)) {wxFAIL; return rc; }
148 // as wxCHECK but with a message explaining why we fail
149 #define wxCHECK_MSG(x, rc, msg) if (!(x)) {wxFAIL_MSG(msg); return rc; }
151 // check that expression is true, perform op if not
152 #define wxCHECK2(x, op) if (!(x)) {wxFAIL; op; }
154 // as wxCHECK2 but with a message explaining why we fail
155 #define wxCHECK2_MSG(x, op, msg) if (!(x)) {wxFAIL_MSG(msg); op; }
157 // special form of wxCHECK2: as wxCHECK, but for use in void functions
159 // NB: there is only one form (with msg parameter) and it's intentional:
160 // there is no other way to tell the caller what exactly went wrong
161 // from the void function (of course, the function shouldn't be void
163 #define wxCHECK_RET(x, msg) if (!(x)) {wxFAIL_MSG(msg); return; }
165 // ----------------------------------------------------------------------------
166 // Compile time asserts
168 // Unlike the normal assert and related macros above which are checked during
169 // the program tun-time the macros below will result in a compilation error if
170 // the condition they check is false. This is usually used to check the
171 // expressions containing sizeof()s which cannot be tested with the
172 // preprocessor. If you can use the #if's, do use them as you can give a more
173 // detailed error message then.
174 // ----------------------------------------------------------------------------
177 How this works (you don't have to understand it to be able to use the
178 macros): we rely on the fact that it is invalid to define a named bit field
179 in a struct of width 0. All the rest are just the hacks to minimize the
180 possibility of the compiler warnings when compiling this macro: in
181 particular, this is why we define a struct and not an object (which would
182 result in a warning about unused variable) and a named struct (otherwise we'd
183 get a warning about an unnamed struct not used to define an object!).
184 The _n__ part is to stop VC++ 7 being confused since it encloses __LINE++ in
185 parentheses. Unfortunately this does not work with MetroWerks CW so this fix
186 is being limited to VC++.
189 #define wxMAKE_ASSERT_NAME_HELPER(line) wxAssert_ ## line
190 #define wxMAKE_ASSERT_NAME(line) wxMAKE_ASSERT_NAME_HELPER(line)
192 #define wxMAKE_UNIQUE_ASSERT_NAME wxMAKE_ASSERT_NAME(_n___ ## __LINE__)
194 #define wxMAKE_UNIQUE_ASSERT_NAME wxMAKE_ASSERT_NAME(__LINE__)
196 #define wxMAKE_UNIQUE_ASSERT_NAME2(text) wxMAKE_ASSERT_NAME(text)
199 The second argument of this macro must be a valid C++ identifier and not a
200 string. I.e. you should use it like this:
202 wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
204 It may be used both within a function and in the global scope.
206 #define wxCOMPILE_TIME_ASSERT(expr, msg) \
207 struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
209 #define wxCOMPILE_TIME_ASSERT2(expr, msg, text) \
210 struct wxMAKE_UNIQUE_ASSERT_NAME2(text) { unsigned int msg: expr; }
212 // helpers for wxCOMPILE_TIME_ASSERT below, for private use only
213 #define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
215 // a special case of compile time assert: check that the size of the given type
216 // is at least the given number of bits
217 #define wxASSERT_MIN_BITSIZE(type, size) \
218 wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
219 wxMAKE_BITSIZE_MSG(type, size))
221 #endif // _WX_DEBUG_H_