added and documented wxCOMPILE_TIME_ASSERT and wxASSERT_MIN_BITSIZE

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@14034 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/function.tex

@@ -9,6 +9,7 @@ the corresponding topic.
 \section{Alphabetical functions and macros list}
 
 \helpref{CLASSINFO}{classinfo}\\
+\helpref{copystring}{copystring}\\
 \helpref{DECLARE\_ABSTRACT\_CLASS}{declareabstractclass}\\
 \helpref{DECLARE\_APP}{declareapp}\\
 \helpref{DECLARE\_CLASS}{declareclass}\\
@@ -23,7 +24,7 @@ the corresponding topic.
 \helpref{WXDEBUG\_NEW}{debugnew}\\
 \helpref{WXTRACELEVEL}{tracelevel}\\
 \helpref{WXTRACE}{trace}\\
-\helpref{copystring}{copystring}\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}\\
 \helpref{wxASSERT\_MSG}{wxassertmsg}\\
 \helpref{wxASSERT}{wxassert}\\
 \helpref{wxBITMAP}{wxbitmapmacro}\\
@@ -39,6 +40,7 @@ the corresponding topic.
 \helpref{wxClipboardOpen}{wxclipboardopen}\\
 \helpref{wxCloseClipboard}{wxcloseclipboard}\\
 \helpref{wxColourDisplay}{wxcolourdisplay}\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}\\
 \helpref{wxConcatFiles}{wxconcatfiles}\\
 \helpref{wxConstCast}{wxconstcast}\\
 \helpref{wxCopyFile}{wxcopyfile}\\
@@ -3320,9 +3322,14 @@ standard usleep() function is not MT safe.
 
 \section{Debugging macros and functions}\label{debugmacros}
 
-Useful macros and functions for error checking and defensive programming. ASSERTs are only
-compiled if \_\_WXDEBUG\_\_ is defined, whereas CHECK macros stay in release
-builds.
+Useful macros and functions for error checking and defensive programming.
+wxWindows defines three families of the assert-like macros:
+the wxASSERT and wxFAIL macros only do anything if \_\_WXDEBUG\_\_ is defined
+(in other words, in the debug build) but disappear completely in the release
+build. On the other hand, the wxCHECK macros stay event in release builds but a
+check failure doesn't generate any user-visible effects then. Finally, the
+compile time assertions don't happen during the run-time but result in the
+compilation error messages if the condition they check fail.
 
 \wxheading{Include files}
 
@@ -3332,10 +3339,15 @@ builds.
 
 \func{void}{wxOnAssert}{\param{const char *}{fileName}, \param{int}{ lineNumber}, \param{const char *}{msg = NULL}}
 
-This function may be redefined to do something non trivial and is called
-whenever one of debugging macros fails (i.e. condition is false in an
-assertion).
-% TODO: this should probably be an overridable in wxApp.
+This function is called whenever one of debugging macros fails (i.e. condition
+is false in an assertion). It is only defined in the debug mode, in release
+builds the \helpref{wxCHECK}{wxcheck} failures don't result in anything.
+
+To override the default behaviour in the debug builds which is to show the user
+a dialog asking whether he wants to abort the program, continue or continue
+ignoring any subsequent assert failures, you may override 
+\helpref{wxApp::OnAssert}{wxapponassert} which is called by this function if
+the global application object exists.
 
 \membersection{wxASSERT}\label{wxassert}
 
@@ -3347,7 +3359,28 @@ debug mode, but nothing will be done in the release build.
 Please note that the condition in wxASSERT() should have no side effects
 because it will not be executed in release mode at all.
 
-See also: \helpref{wxASSERT\_MSG}{wxassertmsg}
+\wxheading{See also}
+
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
+
+\membersection{wxASSERT\_MIN\_BITSIZE}\label{wxassertminbitsize}
+
+\func{}{wxASSERT\_MIN\_BITSIZE}{\param{}{type}, \param{}{size}}
+
+This macro results in a 
+\helpref{compile time assertion failure}{wxCOMPILE\_TIME\_ASSERT} if the size
+of the given type {\it type} is less than {\it size} bits.
+
+You may use it like this, for example:
+
+\begin{verbatim}
+    // we rely on the int being able to hold values up to 2^32
+    wxASSERT_MIN_BITSIZE(int, 32);
+
+    // can't work with the platforms using UTF-8 for wchar_t
+    wxASSERT_MIN_BITSIZE(wchar_t, 16);
+\end{verbatim}
 
 \membersection{wxASSERT\_MSG}\label{wxassertmsg}
 
@@ -3355,7 +3388,28 @@ See also: \helpref{wxASSERT\_MSG}{wxassertmsg}
 
 Assert macro with message. An error message will be generated if the condition is FALSE.
 
-See also: \helpref{wxASSERT}{wxassert}
+\wxheading{See also}
+
+\helpref{wxASSERT}{wxassert},\\
+\helpref{wxCOMPILE\_TIME\_ASSERT}{wxcompiletimeassert}
+
+\membersection{wxCOMPILE\_TIME\_ASSERT}\label{wxcompiletimeassert}
+
+\func{}{wxCOMPILE\_TIME\_ASSERT}{\param{}{condition}, \param{}{msg}}
+
+Using {\tt wxCOMPILE\_TIME\_ASSERT} results in a compilation error if the
+specified {\it condition| is false. The compiler error message should include
+the {\it msg} identifier - please note that it must be a valid C++ identifier
+and not a string unlike in the other cases.
+
+This macro is mostly useful for testing the expressions involing the 
+{\tt sizeof} operator as they can't be tested by the preprocessor but it is
+sometimes desirable to test them at the compile time.
+
+\wxheading{See also}
+
+\helpref{wxASSERT\_MSG}{wxassertmsg},\\
+\helpref{wxASSERT\_MIN\_BITSIZE}{wxassertminbitsize}
 
 \membersection{wxFAIL}\label{wxfail}
 
@@ -3375,7 +3429,9 @@ This macro is useful for marking unreachable" code areas, for example
 it may be used in the "default:" branch of a switch statement if all possible
 cases are processed above.
 
-See also: \helpref{wxFAIL}{wxfail}
+\wxheading{See also}
+
+\helpref{wxFAIL}{wxfail}
 
 \membersection{wxCHECK}\label{wxcheck}
 

include/wx/debug.h

@@ -13,8 +13,9 @@
 #define   _WX_DEBUG_H_
 
 #include  <assert.h>
+#include  <limits.h>            // for CHAR_BIT used below
 
-#include  "wx/wxchar.h"
+#include  "wx/wxchar.h"         // for __TFILE__ and wxChar
 
 // ----------------------------------------------------------------------------
 // Defines controlling the debugging macros
@@ -156,5 +157,50 @@ WXDLLEXPORT_DATA(extern const bool) wxFalse;
 //     to begin with...)
 #define wxCHECK_RET(x, msg)       if (!(x)) {wxFAIL_MSG(msg); return; }
 
+// ----------------------------------------------------------------------------
+// Compile time asserts
+//
+// Unlike the normal assert and related macros above which are checked during
+// the program tun-time the macros below will result in a compilation error if
+// the condition they check is false. This is usually used to check the
+// expressions containing sizeof()s which cannot be tested with the
+// preprocessor. If you can use the #if's, do use them as you can give a more
+// detailed error message then.
+// ----------------------------------------------------------------------------
+
+/*
+  How this works (you don't have to understand it to be able to use the
+  macros): we rely on the fact that it is invalid to define a named bit field
+  in a struct of width 0. All the rest are just the hacks to minimize the
+  possibility of the compiler warnings when compiling this macro: in
+  particular, this is why we define a struct and not an object (which would
+  result in a warning about unused variable) and a named struct (otherwise we'd
+  get a warning about an unnamed struct not used to define an object!).
+ */
+
+#define wxMAKE_ASSERT_NAME_HELPER(line) wxAssert_ ## line
+#define wxMAKE_ASSERT_NAME(line)        wxMAKE_ASSERT_NAME_HELPER(line)
+#define wxMAKE_UNIQUE_ASSERT_NAME       wxMAKE_ASSERT_NAME(__LINE__)
+
+/*
+  The second argument of this macro must be a valid C++ identifier and not a
+  string. I.e. you should use it like this:
+
+    wxCOMPILE_TIME_ASSERT( sizeof(int) >= 2, YourIntsAreTooSmall );
+
+ It may be used both within a function and in the global scope.
+*/
+#define wxCOMPILE_TIME_ASSERT(expr, msg) \
+    struct wxMAKE_UNIQUE_ASSERT_NAME { unsigned int msg: expr; }
+
+// helpers for wxCOMPILE_TIME_ASSERT below, for private use only
+#define wxMAKE_BITSIZE_MSG(type, size) type ## SmallerThan ## size ## Bits
+
+// a special case of compile time assert: check that the size of the given type
+// is at least the given number of bits
+#define wxASSERT_MIN_BITSIZE(type, size) \
+    wxCOMPILE_TIME_ASSERT(sizeof(type) * CHAR_BIT >= size, \
+                          wxMAKE_BITSIZE_MSG(type, size))
+
 #endif  // _WX_DEBUG_H_