Header <boost/static_assert.hpp>Header <boost/static_assert.hpp>The header <boost/static_assert.hpp> supplies a single macro +
The header <boost/static_assert.hpp> supplies a single macro BOOST_STATIC_ASSERT(x), which generates a compile time error message if the integral-constant-expression x is not true. In other words it is the compile time equivalent of the assert macro; this is sometimes known as a @@ -17,7 +25,7 @@ class or function scope. When used in a template, the static assertion will be evaluated at the time the template is instantiated; this is particularly useful for validating template parameters. -
+One of the aims of BOOST_STATIC_ASSERT is to generate readable error messages. These immediately tell the user that a library is being used in a manner that is not supported. While error messages obviously differ from compiler to @@ -28,7 +36,7 @@
You can use BOOST_STATIC_ASSERT at any place where you can place a declaration, that is at class, function or namespace scope, this is illustrated by the following examples:
-The macro can be used at namespace scope, if there is some requirement must always be true; generally this means some platform specific requirement. Suppose we require that int be at least a 32-bit integral type, and that @@ -59,7 +67,7 @@ BOOST_STATIC_ASSERT(WCHAR_MIN >= 0); entitled to emit warnings in such cases). To avoid potential problems, if you use BOOST_STATIC_ASSERT in a header and at namespace scope, then enclose them in a namespace unique to that header.
-The macro is typically used at function scope inside template functions, when the template arguments need checking. Imagine that we have an iterator-based algorithm that requires random access iterators. If the algorithm is @@ -91,7 +99,7 @@ RandomAccessIterator foo(RandomAccessIterator from, RandomAccessIterator to) is_convertible when the conversion is via a user defined constructor (in any case there is no guarantee that the iterator tag classes are copy-constructible).
-The macro is typically used inside classes that are templates. Suppose we have a template-class that requires an unsigned integral type with at least 16-bits of precision as a template argument, we can achieve this using something like @@ -111,7 +119,21 @@ public: /* details here */ }; -
Normally static assertions when used inside a class or function template, will + not be instantiated until the template in which it is used is + instantiated. However, there is one potential problem to watch out for: + if the static assertion is not dependent upon one or + more template parameters, then the compiler is permitted to evaluate the + static assertion at the point it is first seen, irrespective of whether the + template is ever instantiated, for example:
+template <class T>+
struct must_not_be_instantiated
{
BOOST_STATIC_ASSERT(false);
};
Will produce a compiler error with some compilers (for example Intel 8.1 or gcc + 3.4), regardless of whether the template is ever instantiated. A + workaround in cases like this is to force the assertion to be dependent upon a + template parameter:
+template <class T>+
struct must_not_be_instantiated
{
BOOST_STATIC_ASSERT(sizeof(T) == 0); // will be triggered if this type is instantiated
};
BOOST_STATIC_ASSERT works as follows. There is class STATIC_ASSERTION_FAILURE which is defined as:
namespace boost{
@@ -129,7 +151,7 @@ template <> struct STATIC_ASSERTION_FAILURE<true>{};
invent a static assert that avoided macros, all to no avail. The general
conclusion was that the good of a static assert working at namespace, function,
and class scope outweighed the ugliness of a macro.
- Test Programs
+ Test Programs
The following test programs are provided with this library: