feedc0de/boost_static_assert
1
0
Fork 0
forked from boostorg/static_assert
Code Pull Requests Activity

Fixed doc typo.

Browse Source 
[SVN r23427]
This commit is contained in:
John Maddock
2004-07-10 12:36:22 +00:00
parent 68545773d5
commit f0969644d0
1 changed files with 176 additions and 233 deletions
Download Patch File Download Diff File Expand all files Collapse all files

409
static_assert.htm
View File

@ -1,58 +1,40 @@
<html> <html>
<head>
<head> <title>static assertions</title>
<meta http-equiv="Content-Type" <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
content="text/html; charset=iso-8859-1"> <meta name="Template" content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
<meta name="Template" <meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot"> </head>
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0"> <body bgcolor="#ffffff" text="#000000" link="#0000ff" vlink="#800080">
<title>static assertions</title> <h1><img src="../../c++boost.gif" width="276" height="86">Header &lt;<a href="../../boost/static_assert.hpp">boost/static_assert.hpp</a>&gt;</h1>
</head> <p>The header &lt;boost/static_assert.hpp&gt; supplies a single macro
BOOST_STATIC_ASSERT(x), which generates a compile time error message if the <a href="../../more/int_const_guidelines.htm">
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" integral-constant-expression</a> <i>x</i> is not true. In other words it is
vlink="#800080"> 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
<h1><img src="../../c++boost.gif" width="276" height="86">Header these docs. Note that if the condition is true, then the macro will generate
&lt;<a href="../../boost/static_assert.hpp">boost/static_assert.hpp</a>&gt;</h1> 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
<p>The header &lt;boost/static_assert.hpp&gt; supplies a single evaluated at the time the template is instantiated; this is particularly useful
macro BOOST_STATIC_ASSERT(x), which generates a compile time for validating template parameters.
error message if the <a </p>
href="../../more/int_const_guidelines.htm">integral-constant-expression</a> <p>One of the aims of BOOST_STATIC_ASSERT is to generate readable error messages.
<i>x</i> is not true. In other words it is the compile time These immediately tell the user that a library is being used in a manner that
equivalent of the assert macro; this is sometimes known as a is not supported. While error messages obviously differ from compiler to
&quot;compile-time-assertion&quot;, but will be called a &quot;static compiler, but you should see something like:
assertion&quot; throughout these docs. Note that if the condition </p>
is true, then the macro will generate neither code nor data - and <pre>Illegal use of STATIC_ASSERTION_FAILURE&lt;false&gt;</pre>
the macro can also be used at either namespace, class or function <p>Which is intended to at least catch the eye!</p>
scope. When used in a template, the static assertion will be <p>You can use BOOST_STATIC_ASSERT at any place where you can place a declaration,
evaluated at the time the template is instantiated; this is that is at <a href="#class">class</a>, <a href="#function">function</a> or <a href="#namespace">
particularly useful for validating template parameters. </p> namespace</a> scope, this is illustrated by the following examples:</p>
<h3><a name="namespace"></a>Use at namespace scope.</h3>
<p>One of the aims of BOOST_STATIC_ASSERT is to generate readable <p>The macro can be used at namespace scope, if there is some requirement must
error messages. These immediately tell the user that a library is always be true; generally this means some platform specific requirement.
being used in a manner that is not supported. While error Suppose we require that <b>int</b> be at least a 32-bit integral type, and that <b>
messages obviously differ from compiler to compiler, but you wchar_t</b> be an unsigned type. We can verify this at compile time as
should see something like: </p> follows:</p>
<pre>#include &lt;climits&gt;
<pre>Illegal use of COMPILE_TIME_ASSERTION_FAILURE&lt;false&gt;</pre>
<p>Which is intended to at least catch the eye!</p>
<p>You can use BOOST_STATIC_ASSERT at any place where you can
place a declaration, that is at <a href="#class">class</a>, <a
href="#function">function</a> or <a href="#namespace">namespace</a>
scope, this is illustrated by the following examples:</p>
<h3><a name="namespace"></a>Use at namespace scope.</h3>
<p>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 <b>int</b>
be at least a 32-bit integral type, and that <b>wchar_t</b> be an
unsigned type. We can verify this at compile time as follows:</p>
<pre>#include &lt;climits&gt;
#include &lt;cwchar&gt; #include &lt;cwchar&gt;
#include &lt;boost/static_assert.hpp&gt; #include &lt;boost/static_assert.hpp&gt;
@ -63,40 +45,31 @@ BOOST_STATIC_ASSERT(WCHAR_MIN &gt;= 0);
} // namespace my_conditions } // namespace my_conditions
</pre> </pre>
<p>The use of the namespace <i>my_conditions</i> here requires some comment. The
<p>The use of the namespace <i>my_conditions</i> here requires macro BOOST_STATIC_ASSERT works by generating an <strong>typedef</strong> declaration,
some comment. The macro BOOST_STATIC_ASSERT works by generating and since the typedef must have a name, the macro generates one automatically
an <strong>typedef</strong> declaration, and since the typedef by mangling a stub name with the value of __LINE__. When BOOST_STATIC_ASSERT is
must have a name, the macro generates one automatically by used at either class or function scope then each use of BOOST_STATIC_ASSERT is
mangling a stub name with the value of __LINE__. When guaranteed to produce a name unique to that scope (provided you only use the
BOOST_STATIC_ASSERT is used at either class or function scope macro once on each line). However when used in a header at namespace scope,
then each use of BOOST_STATIC_ASSERT is guaranteed to produce a that namespace can be continued over multiple headers, each of which may have
name unique to that scope (provided you only use the macro once their own static assertions, and on the "same" lines, thereby generating
on each line). However when used in a header at namespace scope, duplicate declarations. In theory the compiler should silently ignore duplicate
that namespace can be continued over multiple headers, each of typedef declarations, however many do not do so (and even if they do they are
which may have their own static assertions, and on the &quot;same&quot; entitled to emit warnings in such cases). To avoid potential problems, if you
lines, thereby generating duplicate declarations. In theory the use BOOST_STATIC_ASSERT in a header and at namespace scope, then enclose them
compiler should silently ignore duplicate typedef declarations, in a namespace unique to that header.</p>
however many do not do so (and even if they do they are entitled <h3><a name="function"></a>Use at function scope</h3>
to emit warnings in such cases). To avoid potential problems, if <p>The macro is typically used at function scope inside template functions, when
you use BOOST_STATIC_ASSERT in a header and at namespace scope, the template arguments need checking. Imagine that we have an iterator-based
then enclose them in a namespace unique to that header.</p> algorithm that requires random access iterators. If the algorithm is
instantiated with iterators that do not meet our requirements then an error
<h3><a name="function"></a>Use at function scope</h3> 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
<p>The macro is typically used at function scope inside template is to add a static assertion at the top level of the template, in that case if
functions, when the template arguments need checking. Imagine the condition is not met, then an error will be generated in a way that makes
that we have an iterator-based algorithm that requires random it reasonably obvious to the user that the template is being misused.</p>
access iterators. If the algorithm is instantiated with iterators <pre>#include &lt;iterator&gt;
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.</p>
<pre>#include &lt;iterator&gt;
#include &lt;boost/static_assert.hpp&gt; #include &lt;boost/static_assert.hpp&gt;
#include &lt;boost/type_traits.hpp&gt; #include &lt;boost/type_traits.hpp&gt;
@ -111,24 +84,19 @@ RandomAccessIterator foo(RandomAccessIterator from, RandomAccessIterator to)
// detail goes here... // detail goes here...
return from; return from;
}</pre> }</pre>
<p>A couple of footnotes are in order here: the extra set of parenthesis around
<p>A couple of footnotes are in order here: the extra set of the assert, is to prevent the comma inside the is_convertible template being
parenthesis around the assert, is to prevent the comma inside the interpreted by the preprocessor as a macro argument separator; the target type
is_convertible template being interpreted by the preprocessor as for is_convertible is a reference type, as some compilers have problems using
a macro argument separator; the target type for is_convertible is is_convertible when the conversion is via a user defined constructor (in any
a reference type, as some compilers have problems using case there is no guarantee that the iterator tag classes are
is_convertible when the conversion is via a user defined copy-constructible).</p>
constructor (in any case there is no guarantee that the iterator <h3><a name="class"></a>Use at class scope</h3>
tag classes are copy-constructible).</p> <p>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
<h3><a name="class"></a>Use at class scope</h3> of precision as a template argument, we can achieve this using something like
this:</p>
<p>The macro is typically used inside classes that are templates. <pre>#include &lt;climits&gt;
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:</p>
<pre>#include &lt;climits&gt;
#include &lt;boost/static_assert.hpp&gt; #include &lt;boost/static_assert.hpp&gt;
template &lt;class UnsignedInt&gt; template &lt;class UnsignedInt&gt;
@ -143,137 +111,112 @@ public:
/* details here */ /* details here */
}; };
</pre> </pre>
<h3>How it works</h3>
<h3>How it works</h3> <p>BOOST_STATIC_ASSERT works as follows. There is class STATIC_ASSERTION_FAILURE
which is defined as:</p>
<p>BOOST_STATIC_ASSERT works as follows. There is class <pre>namespace boost{
STATIC_ASSERTION_FAILURE which is defined as:</p>
<pre>namespace boost{
template &lt;bool&gt; struct STATIC_ASSERTION_FAILURE; template &lt;bool&gt; struct STATIC_ASSERTION_FAILURE;
template &lt;&gt; struct STATIC_ASSERTION_FAILURE&lt;true&gt;{}; template &lt;&gt; struct STATIC_ASSERTION_FAILURE&lt;true&gt;{};
}</pre> }</pre>
<p>The key feature is that the error message triggered by the undefined expression
<p>The key feature is that the error message triggered by the sizeof(STATIC_ASSERTION_FAILURE&lt;0&gt;), tends to be consistent across a wide
undefined expression sizeof(STATIC_ASSERTION_FAILURE&lt;0&gt;), variety of compilers. The rest of the machinery of BOOST_STATIC_ASSERT is just
tends to be consistent across a wide variety of compilers. The a way to feed the sizeof expression into a typedef. The use of a macro here is
rest of the machinery of BOOST_STATIC_ASSERT is just a way to somewhat ugly; however boost members have spent considerable effort trying to
feed the sizeof expression into a typedef. The use of a macro invent a static assert that avoided macros, all to no avail. The general
here is somewhat ugly; however boost members have spent conclusion was that the good of a static assert working at namespace, function,
considerable effort trying to invent a static assert that avoided and class scope outweighed the ugliness of a macro.</p>
macros, all to no avail. The general conclusion was that the good <h3>Test Programs</h3>
of a static assert working at namespace, function, and class <p>The following test programs are provided with this library:</p>
scope outweighed the ugliness of a macro.</p> <table border="0" width="100%">
<tr>
<h3>Test Programs</h3> <td width="33%"><i>Test Program</i></td>
<td width="33%"><i>Expected to Compile</i></td>
<p>The following test programs are provided with this library:</p> <td width="34%"><i>Description</i></td>
</tr>
<table border="0" width="100%"> <tr>
<tr> <td width="33%"><a href="static_assert_test.cpp">static_assert_test.cpp</a></td>
<td width="33%"><i>Test Program</i></td> <td width="33%">Yes</td>
<td width="33%"><i>Expected to Compile</i></td> <td width="34%">Illustrates usage, and should always compile, really just tests
<td width="34%"><i>Description</i></td> compiler compatibility.</td>
</tr> </tr>
<tr> <tr>
<td width="33%"><a href="static_assert_test.cpp">static_assert_test.cpp</a></td> <td width="33%"><a href="static_assert_example_1.cpp">static_assert_example_1.cpp</a></td>
<td width="33%">Yes</td> <td width="33%">Platform dependent.</td>
<td width="34%">Illustrates usage, and should always <td width="34%">Namespace scope test program, may compile depending upon the
compile, really just tests compiler compatibility.</td> platform.</td>
</tr> </tr>
<tr> <tr>
<td width="33%"><a href="static_assert_example_1.cpp">static_assert_example_1.cpp</a></td> <td width="33%"><a href="static_assert_example_2.cpp">static_assert_example_2.cpp</a></td>
<td width="33%">Platform dependent.</td> <td width="33%">Yes</td>
<td width="34%">Namespace scope test program, may compile <td width="34%">Function scope test program.</td>
depending upon the platform.</td> </tr>
</tr> <tr>
<tr> <td width="33%"><a href="static_assert_example_3.cpp">static_assert_example_3.cpp</a></td>
<td width="33%"><a href="static_assert_example_2.cpp">static_assert_example_2.cpp</a></td> <td width="33%">Yes</td>
<td width="33%">Yes</td> <td width="34%">Class scope test program.</td>
<td width="34%">Function scope test program.</td> </tr>
</tr> <tr>
<tr> <td width="33%"><a href="static_assert_test_fail_1.cpp">static_assert_test_fail_1.cpp</a></td>
<td width="33%"><a href="static_assert_example_3.cpp">static_assert_example_3.cpp</a></td> <td width="33%">No</td>
<td width="33%">Yes</td> <td width="34%">Illustrates failure at namespace scope.</td>
<td width="34%">Class scope test program.</td> </tr>
</tr> <tr>
<tr> <td width="33%"><a href="static_assert_test_fail_2.cpp">static_assert_test_fail_2.cpp</a></td>
<td width="33%"><a href="static_assert_test_fail_1.cpp">static_assert_test_fail_1.cpp</a></td> <td width="33%">No</td>
<td width="33%">No</td> <td width="34%">Illustrates failure at non-template function scope.</td>
<td width="34%">Illustrates failure at namespace scope.</td> </tr>
</tr> <tr>
<tr> <td width="33%"><a href="static_assert_test_fail_3.cpp">static_assert_test_fail_3.cpp</a></td>
<td width="33%"><a href="static_assert_test_fail_2.cpp">static_assert_test_fail_2.cpp</a></td> <td width="33%">No</td>
<td width="33%">No</td> <td width="34%">Illustrates failure at non-template class scope.</td>
<td width="34%">Illustrates failure at non-template </tr>
function scope.</td> <tr>
</tr> <td width="33%"><a href="static_assert_test_fail_4.cpp">static_assert_test_fail_4.cpp</a></td>
<tr> <td width="33%">No</td>
<td width="33%"><a href="static_assert_test_fail_3.cpp">static_assert_test_fail_3.cpp</a></td> <td width="34%">Illustrates failure at non-template class scope.</td>
<td width="33%">No</td> </tr>
<td width="34%">Illustrates failure at non-template class <tr>
scope.</td> <td width="33%"><a href="static_assert_test_fail_5.cpp">static_assert_test_fail_5.cpp</a></td>
</tr> <td width="33%">No</td>
<tr> <td width="34%">Illustrates failure at template class scope.</td>
<td width="33%"><a href="static_assert_test_fail_4.cpp">static_assert_test_fail_4.cpp</a></td> </tr>
<td width="33%">No</td> <tr>
<td width="34%">Illustrates failure at non-template class <td width="33%"><a href="static_assert_test_fail_6.cpp">static_assert_test_fail_6.cpp</a></td>
scope.</td> <td width="33%">No</td>
</tr> <td width="34%">Illustrates failure at template class member function scope.</td>
<tr> </tr>
<td width="33%"><a href="static_assert_test_fail_5.cpp">static_assert_test_fail_5.cpp</a></td> <tr>
<td width="33%">No</td> <td width="33%"><a href="static_assert_test_fail_7.cpp">static_assert_test_fail_7.cpp</a></td>
<td width="34%">Illustrates failure at template class <td width="33%">No</td>
scope.</td> <td width="34%">Illustrates failure of class scope example.</td>
</tr> </tr>
<tr> <tr>
<td width="33%"><a href="static_assert_test_fail_6.cpp">static_assert_test_fail_6.cpp</a></td> <td><a href="static_assert_test_fail_8.cpp">static_assert_test_fail_8.cpp</a></td>
<td width="33%">No</td> <td>No</td>
<td width="34%">Illustrates failure at template class <td>Illustrates failure of function scope example.</td>
member function scope.</td> </tr>
</tr> <tr>
<tr> <td><a href="static_assert_test_fail_9.cpp">static_assert_test_fail_9.cpp</a></td>
<td width="33%"><a href="static_assert_test_fail_7.cpp">static_assert_test_fail_7.cpp</a></td> <td>No</td>
<td width="33%">No</td> <td>Illustrates failure of function scope example (part 2).</td>
<td width="34%">Illustrates failure of class scope </tr>
example.</td> </table>
</tr> <hr>
<tr> <p>Revised 27th Nov 2000</p>
<td><a href="static_assert_test_fail_8.cpp">static_assert_test_fail_8.cpp</a></td> <p>Documentation <20> Copyright John Maddock 2000. Permission to copy, use, modify,
<td>No</td> sell and distribute this document is granted provided this copyright notice
<td>Illustrates failure of function scope example.</td> appears in all copies. This document is provided "as is" without express or
</tr> implied warranty, and with no claim as to its suitability for any purpose.</p>
<tr> <p>Based on contributions by Steve Cleary and John Maddock.</p>
<td><a href="static_assert_test_fail_9.cpp">static_assert_test_fail_9.cpp</a></td> <p>Maintained by <a href="mailto:john@johnmaddock.co.uk">John Maddock</a>, the
<td>No</td> latest version of this file can be found at <a href="http://www.boost.org/">www.boost.org</a>,
<td>Illustrates failure of function scope example (part 2).</td> and the boost discussion list at <a href="http://www.yahoogroups.com/list/boost">www.yahoogroups.com/list/boost</a>.
</tr> </p>
</table> <p>&nbsp;</p>
<p>&nbsp;</p>
<hr> </body>
<p>Revised 27th Nov 2000</p>
<p>Documentation <20> 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 &quot;as is&quot; without express or implied
warranty, and with no claim as to its suitability for any purpose.</p>
<p>Based on contributions by Steve Cleary and John Maddock.</p>
<p>Maintained by <a href="mailto:john@johnmaddock.co.uk">John
Maddock</a>, the latest version of this file can be found at <a
href="http://www.boost.org/">www.boost.org</a>, and the boost
discussion list at <a
href="http://www.yahoogroups.com/list/boost">www.yahoogroups.com/list/boost</a>.
</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
</body>
</html> </html>