boostorg/static_assert
1
0
Fork 1
mirror of https://github.com/boostorg/static_assert.git synced 2025-07-23 17:27:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

added integral constant expression links, added tentative fix to is_function_test for older EDG based compilers

Browse Source 
[SVN r9833]
This commit is contained in:
John Maddock
2001-04-18 11:28:53 +00:00
parent 1cd7ee8570
commit 362a22e3a7
1 changed files with 230 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

433
static_assert.htm
View File

@ -1,45 +1,58 @@
<!DOCTYPE HTML PUBLIC "-//SoftQuad Software//DTD HoTMetaL PRO 5.0::19981217::extensions to HTML 4.0//EN" "hmpro5.dtd"> <html>
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Template"
CONTENT="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
<META NAME="GENERATOR" CONTENT="Microsoft FrontPage 4.0">
<TITLE>static assertions</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080"> <head>
<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> <meta http-equiv="Content-Type"
<P>The header &lt;boost/static_assert.hpp&gt; supplies a single macro content="text/html; charset=iso-8859-1">
BOOST_STATIC_ASSERT(x), which generates a compile time error message if the <meta name="Template"
integral-constant-expression <I>x</I> is not true. In other words it is the content="C:\PROGRAM FILES\MICROSOFT OFFICE\OFFICE\html.dot">
compile time equivalent of the assert macro; this is sometimes known as a <meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title>static assertions</title>
</head>
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
vlink="#800080">
<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>
<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/integral_constant_guidelines.htm">integral-constant-expression</a>
<i>x</i> is not true. In other words it is the compile time
equivalent of the assert macro; this is sometimes known as a
&quot;compile-time-assertion&quot;, but will be called a &quot;static &quot;compile-time-assertion&quot;, but will be called a &quot;static
assertion&quot; throughout these docs. Note that if the condition is true, then assertion&quot; throughout these docs. Note that if the condition
the macro will generate neither code nor data - and the macro can also be used is true, then the macro will generate neither code nor data - and
at either namespace, class or function scope. When used in a template, the the macro can also be used at either namespace, class or function
static assertion will be evaluated at the time the template is instantiated; scope. When used in a template, the static assertion will be
this is particularly useful for validating template parameters. </P> evaluated at the time the template is instantiated; this is
<P>One of the aims of BOOST_STATIC_ASSERT is to generate readable error particularly useful for validating template parameters. </p>
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: </P>
<PRE>Illegal use of COMPILE_TIME_ASSERTION_FAILURE&lt;false&gt;</PRE>
<P>Which is intended to at least catch the eye!</P> <p>One of the aims of BOOST_STATIC_ASSERT is to generate readable
<P>You can use BOOST_STATIC_ASSERT at any place where you can place a error messages. These immediately tell the user that a library is
declaration, that is at <A HREF="#class">class</A>, <A being used in a manner that is not supported. While error
HREF="#function">function</A> or <A HREF="#namespace">namespace</A> scope, this messages obviously differ from compiler to compiler, but you
is illustrated by the following examples:</P> should see something like: </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 <pre>Illegal use of COMPILE_TIME_ASSERTION_FAILURE&lt;false&gt;</pre>
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 <p>Which is intended to at least catch the eye!</p>
<B>wchar_t</B> be an unsigned type. We can verify this at compile time as
follows:</P> <p>You can use BOOST_STATIC_ASSERT at any place where you can
<PRE>#include &lt;climits&gt; 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;
@ -49,35 +62,41 @@ BOOST_STATIC_ASSERT(sizeof(int) * CHAR_BIT &gt;= 32);
BOOST_STATIC_ASSERT(WCHAR_MIN &gt;= 0); 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. <p>The use of the namespace <i>my_conditions</i> here requires
The macro BOOST_STATIC_ASSERT works by generating an <STRONG>typedef</STRONG> some comment. The macro BOOST_STATIC_ASSERT works by generating
declaration, and since the typedef must have a name, the macro generates one an <strong>typedef</strong> declaration, and since the typedef
automatically by mangling a stub name with the value of __LINE__. When must have a name, the macro generates one automatically by
BOOST_STATIC_ASSERT is used at either class or function scope then each use of mangling a stub name with the value of __LINE__. When
BOOST_STATIC_ASSERT is guaranteed to produce a name unique to that scope BOOST_STATIC_ASSERT is used at either class or function scope
(provided you only use the macro once on each line). However when used in a then each use of BOOST_STATIC_ASSERT is guaranteed to produce a
header at namespace scope, that namespace can be continued over multiple name unique to that scope (provided you only use the macro once
headers, each of which may have their own static assertions, and on the on each line). However when used in a header at namespace scope,
&quot;same&quot; lines, thereby generating duplicate declarations. In theory that namespace can be continued over multiple headers, each of
the compiler should silently ignore duplicate typedef declarations, however which may have their own static assertions, and on the &quot;same&quot;
many do not do so (and even if they do they are entitled to emit warnings in lines, thereby generating duplicate declarations. In theory the
such cases). To avoid potential problems, if you use BOOST_STATIC_ASSERT in a compiler should silently ignore duplicate typedef declarations,
header and at namespace scope, then enclose them in a namespace unique to that however many do not do so (and even if they do they are entitled
header.</P> to emit warnings in such cases). To avoid potential problems, if
<H3><A NAME="function"></A>Use at function scope</H3> you use BOOST_STATIC_ASSERT in a header and at namespace scope,
<P>The macro is typically used at function scope inside template functions, then enclose them in a namespace unique to that header.</p>
when the template arguments need checking. Imagine that we have an
iterator-based algorithm that requires random access iterators. If the <h3><a name="function"></a>Use at function scope</h3>
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 <p>The macro is typically used at function scope inside template
several templates, making it hard for the user to determine what went wrong. functions, when the template arguments need checking. Imagine
One option is to add a static assertion at the top level of the template, in that we have an iterator-based algorithm that requires random
that case if the condition is not met, then an error will be generated in a way access iterators. If the algorithm is instantiated with iterators
that makes it reasonably obvious to the user that the template is being that do not meet our requirements then an error will be generated
misused.</P> eventually, but this may be nested deep inside several templates,
<PRE>#include &lt;iterator&gt; 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;
@ -91,21 +110,25 @@ 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 <h3><a name="class"></a>Use at class scope</h3>
16-bits 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; Template &lt;class UnsignedInt&gt;template &lt;class UnsignedInt&gt;
@ -119,133 +142,137 @@ private:
public: 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 <p>The key feature is that the error message triggered by the
expression sizeof(STATIC_ASSERTION_FAILURE&lt;0&gt;), tends to be consistent undefined expression sizeof(STATIC_ASSERTION_FAILURE&lt;0&gt;),
across a wide variety of compilers. The rest of the machinery of tends to be consistent across a wide variety of compilers. The
BOOST_STATIC_ASSERT is just a way to feed the sizeof expression into a typedef. rest of the machinery of BOOST_STATIC_ASSERT is just a way to
The use of a macro here is somewhat ugly; however boost members have spent feed the sizeof expression into a typedef. The use of a macro
considerable effort trying to invent a static assert that avoided macros, all here is somewhat ugly; however boost members have spent
to no avail. The general conclusion was that the good of a static assert considerable effort trying to invent a static assert that avoided
working at namespace, function, and class scope outweighed the ugliness of a macros, all to no avail. The general conclusion was that the good
macro.</P> of a static assert working at namespace, function, and class
<H3>Test Programs</H3> scope outweighed the ugliness of a macro.</p>
<P>The following test programs are provided with this library:</P>
<TABLE BORDER="0" WIDTH="100%">
<TR>
<TD WIDTH="33%"><I>Test Program</I></TD>
<TD WIDTH="33%"><I>Expected to Compile</I></TD>
<TD WIDTH="34%"><I>Description</I></TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_test.cpp">static_assert_test.cpp</A></TD>
<TD WIDTH="33%">Yes</TD>
<TD WIDTH="34%">Illustrates usage, and should always compile, really just tests
compiler compatibility.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_example_1.cpp">static_assert_example_1.cpp</A></TD>
<TD WIDTH="33%">Platform dependent.</TD>
<TD WIDTH="34%">Namespace scope test program, may compile depending upon the
platform.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_example_2.cpp">static_assert_example_2.cpp</A></TD>
<TD WIDTH="33%">Yes</TD>
<TD WIDTH="34%">Function scope test program.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_example_3.cpp">static_assert_example_3.cpp</A></TD>
<TD WIDTH="33%">Yes</TD>
<TD WIDTH="34%">Class scope test program.</TD>
</TR>
<TR>
<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="34%">Illustrates failure at namespace scope.</TD>
</TR>
<TR>
<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="34%">Illustrates failure at non-template function scope.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_test_fail_3.cpp">static_assert_test_fail_3.cpp</A></TD>
<TD WIDTH="33%">No</TD>
<TD WIDTH="34%">Illustrates failure at non-template class scope.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_test_fail_4.cpp">static_assert_test_fail_4.cpp</A></TD>
<TD WIDTH="33%">No</TD>
<TD WIDTH="34%">Illustrates failure at non-template class scope.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_test_fail_5.cpp">static_assert_test_fail_5.cpp</A></TD>
<TD WIDTH="33%">No</TD>
<TD WIDTH="34%">Illustrates failure at template class scope.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_test_fail_6.cpp">static_assert_test_fail_6.cpp</A></TD>
<TD WIDTH="33%">No</TD>
<TD WIDTH="34%">Illustrates failure at template class member function
scope.</TD>
</TR>
<TR>
<TD WIDTH="33%"><A
HREF="static_assert_test_fail_7.cpp">static_assert_test_fail_7.cpp</A></TD>
<TD WIDTH="33%">No</TD>
<TD WIDTH="34%">Illustrates failure of class scope example.</TD>
</TR>
<TR>
<TD><A
HREF="static_assert_test_fail_8.cpp">static_assert_test_fail_8.cpp</A></TD>
<TD>No</TD>
<TD>Illustrates failure of function scope example.</TD>
</TR>
<TR>
<TD><A
HREF="static_assert_test_fail_9.cpp">static_assert_test_fail_9.cpp</A></TD>
<TD>No</TD>
<TD>Illustrates failure of function scope example (part 2).</TD>
</TR>
</TABLE>
<HR>
<P>Revised 27th Nov 2000</P>
<P>Documentation &copy; 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_Maddock@compuserve.com">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.egroups.com/list/boost">www.egroups.com/list/boost</A>.
</P>
<P>&nbsp;</P>
<P>&nbsp;</P>
</BODY>
</HTML>
<h3>Test Programs</h3>
<p>The following test programs are provided with this library:</p>
<table border="0" width="100%">
<tr>
<td width="33%"><i>Test Program</i></td>
<td width="33%"><i>Expected to Compile</i></td>
<td width="34%"><i>Description</i></td>
</tr>
<tr>
<td width="33%"><a href="static_assert_test.cpp">static_assert_test.cpp</a></td>
<td width="33%">Yes</td>
<td width="34%">Illustrates usage, and should always
compile, really just tests compiler compatibility.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_example_1.cpp">static_assert_example_1.cpp</a></td>
<td width="33%">Platform dependent.</td>
<td width="34%">Namespace scope test program, may compile
depending upon the platform.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_example_2.cpp">static_assert_example_2.cpp</a></td>
<td width="33%">Yes</td>
<td width="34%">Function scope test program.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_example_3.cpp">static_assert_example_3.cpp</a></td>
<td width="33%">Yes</td>
<td width="34%">Class scope test program.</td>
</tr>
<tr>
<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="34%">Illustrates failure at namespace scope.</td>
</tr>
<tr>
<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="34%">Illustrates failure at non-template
function scope.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_test_fail_3.cpp">static_assert_test_fail_3.cpp</a></td>
<td width="33%">No</td>
<td width="34%">Illustrates failure at non-template class
scope.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_test_fail_4.cpp">static_assert_test_fail_4.cpp</a></td>
<td width="33%">No</td>
<td width="34%">Illustrates failure at non-template class
scope.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_test_fail_5.cpp">static_assert_test_fail_5.cpp</a></td>
<td width="33%">No</td>
<td width="34%">Illustrates failure at template class
scope.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_test_fail_6.cpp">static_assert_test_fail_6.cpp</a></td>
<td width="33%">No</td>
<td width="34%">Illustrates failure at template class
member function scope.</td>
</tr>
<tr>
<td width="33%"><a href="static_assert_test_fail_7.cpp">static_assert_test_fail_7.cpp</a></td>
<td width="33%">No</td>
<td width="34%">Illustrates failure of class scope
example.</td>
</tr>
<tr>
<td><a href="static_assert_test_fail_8.cpp">static_assert_test_fail_8.cpp</a></td>
<td>No</td>
<td>Illustrates failure of function scope example.</td>
</tr>
<tr>
<td><a href="static_assert_test_fail_9.cpp">static_assert_test_fail_9.cpp</a></td>
<td>No</td>
<td>Illustrates failure of function scope example (part 2).</td>
</tr>
</table>
<hr>
<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_Maddock@compuserve.com">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.egroups.com/list/boost">www.egroups.com/list/boost</a>.
</p>
<p>&nbsp;</p>
<p>&nbsp;</p>
</body>
</html>