From 3959c96e2600d6a242999561a3b131f6b27899ae Mon Sep 17 00:00:00 2001 From: John Maddock Date: Sun, 24 Apr 2005 12:01:56 +0000 Subject: [PATCH] Fix up docs to point to new BoostBook versions. [SVN r28460] --- index.html | 21 ++-- static_assert.htm | 254 +++------------------------------------------- 2 files changed, 25 insertions(+), 250 deletions(-) diff --git a/index.html b/index.html index bf8a7a8..2a7339e 100644 --- a/index.html +++ b/index.html @@ -1,9 +1,14 @@ + - - - - -Automatic redirection failed, please go to -static_assert.htm. - - \ No newline at end of file + + + + + Automatic redirection failed, please go to + ../../doc/html/boost_staticassert.html + or view the online version at + + http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boost_staticassert.html + + + diff --git a/static_assert.htm b/static_assert.htm index 6e51984..2a7339e 100644 --- a/static_assert.htm +++ b/static_assert.htm @@ -1,244 +1,14 @@ + - - static assertions - - - - - -

Header <boost/static_assert.hpp>

-

Contents

-
-
Overview
Use at namespace scope -
Use at function scope
Use at class - scope
Use in templates
How it - works
Test programs
-
-

Overview

-

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 - "compile-time-assertion", but will be called a "static assertion" throughout - these docs. Note that if the condition is true, then the macro will generate - neither code nor data - and the macro can also be used at either namespace, - 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 - compiler, but you should see something like: -

- 
Illegal use of STATIC_ASSERTION_FAILURE<false>
-

Which is intended to at least catch the eye!

-

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:

-

Use at namespace scope.

-

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 - wchar_t be an unsigned type. We can verify this at compile time as - follows:

- 
#include <climits>
-#include <cwchar>
-#include <boost/static_assert.hpp>
-
-namespace my_conditions {
-
-BOOST_STATIC_ASSERT(sizeof(int) * CHAR_BIT >= 32);
-BOOST_STATIC_ASSERT(WCHAR_MIN >= 0);
-
-} // namespace my_conditions
-
-

The use of the namespace my_conditions here requires some comment. The - macro BOOST_STATIC_ASSERT works by generating an typedef declaration, - and since the typedef must have a name, the macro generates one automatically - by mangling a stub name with the value of __LINE__. When BOOST_STATIC_ASSERT is - used at either class or function scope then each use of BOOST_STATIC_ASSERT is - guaranteed to produce a name unique to that scope (provided you only use the - macro once on each line). However when used in a header at namespace scope, - that namespace can be continued over multiple headers, each of which may have - their own static assertions, and on the "same" lines, thereby generating - duplicate declarations. In theory the compiler should silently ignore duplicate - typedef declarations, however many do not do so (and even if they do they are - 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.

-

Use at function scope

-

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 - instantiated with iterators that do not meet our requirements then an error - will be generated eventually, but this may be nested deep inside several - templates, making it hard for the user to determine what went wrong. One option - is to add a static assertion at the top level of the template, in that case if - the condition is not met, then an error will be generated in a way that makes - it reasonably obvious to the user that the template is being misused.

- 
#include <iterator>
-#include <boost/static_assert.hpp>
-#include <boost/type_traits.hpp>
-
-template <class RandomAccessIterator >
-RandomAccessIterator foo(RandomAccessIterator from, RandomAccessIterator to)
-{
-   // this template can only be used with
-   // random access iterators...
-   typedef typename std::iterator_traits< RandomAccessIterator >::iterator_category cat;
-   BOOST_STATIC_ASSERT((boost::is_convertible<cat, const std::random_access_iterator_tag&>::value));
-   //
-   // detail goes here...
-   return from;
-}
-

A couple of footnotes are in order here: the extra set of parenthesis around - the assert, is to prevent the comma inside the is_convertible template being - interpreted by the preprocessor as a macro argument separator; the target type - for is_convertible is a reference type, as some compilers have problems using - 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).

-

Use at class scope

-

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 - this:

- 
#include <climits>
-#include <boost/static_assert.hpp>
-
-template <class UnsignedInt>
-class myclass
-{
-private:
-   BOOST_STATIC_ASSERT(sizeof(UnsignedInt) * CHAR_BIT >= 16);
-   BOOST_STATIC_ASSERT(std::numeric_limits<UnsignedInt>::is_specialized
-                        && std::numeric_limits<UnsignedInt>::is_integer
-                        && !std::numeric_limits<UnsignedInt>::is_signed);
-public:
-   /* details here */
-};
-
-

Use in templates

-

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



};
-

How it works

-

BOOST_STATIC_ASSERT works as follows. There is class STATIC_ASSERTION_FAILURE - which is defined as:

- 
namespace boost{
-
-template <bool> struct STATIC_ASSERTION_FAILURE;
-
-template <> struct STATIC_ASSERTION_FAILURE<true>{};
-
-}
-

The key feature is that the error message triggered by the undefined expression - sizeof(STATIC_ASSERTION_FAILURE<0>), tends to be consistent across a wide - variety of compilers. The rest of the machinery of BOOST_STATIC_ASSERT is just - a way to feed the sizeof expression into a typedef. The use of a macro here is - somewhat ugly; however boost members have spent considerable effort trying to - 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

-

The following test programs are provided with this library:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Test ProgramExpected to CompileDescription
static_assert_test.cppYesIllustrates usage, and should always compile, really just tests - compiler compatibility.
static_assert_example_1.cppPlatform dependent.Namespace scope test program, may compile depending upon the - platform.
static_assert_example_2.cppYesFunction scope test program.
static_assert_example_3.cppYesClass scope test program.
static_assert_test_fail_1.cppNoIllustrates failure at namespace scope.
static_assert_test_fail_2.cppNoIllustrates failure at non-template function scope.
static_assert_test_fail_3.cppNoIllustrates failure at non-template class scope.
static_assert_test_fail_4.cppNoIllustrates failure at non-template class scope.
static_assert_test_fail_5.cppNoIllustrates failure at template class scope.
static_assert_test_fail_6.cppNoIllustrates failure at template class member function scope.
static_assert_test_fail_7.cppNoIllustrates failure of class scope example.
static_assert_test_fail_8.cppNoIllustrates failure of function scope example.
static_assert_test_fail_9.cppNoIllustrates failure of function scope example (part 2).
-
-

Revised 27th Nov 2000

-

Documentation © Copyright John Maddock 2000. Permission to copy, use, modify, - sell and distribute this document is granted provided this copyright notice - appears in all copies. This document is provided "as is" without express or - implied warranty, and with no claim as to its suitability for any purpose.

-

Based on contributions by Steve Cleary and John Maddock.

-

Maintained by John Maddock, the - latest version of this file can be found at www.boost.org, - and the boost discussion list at www.yahoogroups.com/list/boost. -

-

 

-

 

- + + + + + Automatic redirection failed, please go to + ../../doc/html/boost_staticassert.html + or view the online version at + + http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boost_staticassert.html + +