| [12] | 1 | <html> |
|---|
| 2 | <head> |
|---|
| 3 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
|---|
| 4 | <title>Chapter 10. Boost.StaticAssert</title> |
|---|
| 5 | <link rel="stylesheet" href="boostbook.css" type="text/css"> |
|---|
| 6 | <meta name="generator" content="DocBook XSL Stylesheets V1.69.1"> |
|---|
| 7 | <link rel="start" href="index.html" title="The Boost C++ Libraries"> |
|---|
| 8 | <link rel="up" href="libraries.html" title="Part I. The Boost C++ Libraries"> |
|---|
| 9 | <link rel="prev" href="signals/tests.html" title="Testsuite"> |
|---|
| 10 | <link rel="next" href="boost_staticassert/how.html" title=" How it works"> |
|---|
| 11 | </head> |
|---|
| 12 | <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
|---|
| 13 | <table cellpadding="2" width="100%"> |
|---|
| 14 | <td valign="top"><img alt="boost.png (6897 bytes)" width="277" height="86" src="../../boost.png"></td> |
|---|
| 15 | <td align="center"><a href="../../index.htm">Home</a></td> |
|---|
| 16 | <td align="center"><a href="../../libs/libraries.htm">Libraries</a></td> |
|---|
| 17 | <td align="center"><a href="../../people/people.htm">People</a></td> |
|---|
| 18 | <td align="center"><a href="../../more/faq.htm">FAQ</a></td> |
|---|
| 19 | <td align="center"><a href="../../more/index.htm">More</a></td> |
|---|
| 20 | </table> |
|---|
| 21 | <hr> |
|---|
| 22 | <div class="spirit-nav"> |
|---|
| 23 | <a accesskey="p" href="signals/tests.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="boost_staticassert/how.html"><img src="images/next.png" alt="Next"></a> |
|---|
| 24 | </div> |
|---|
| 25 | <div class="chapter" lang="en"> |
|---|
| 26 | <div class="titlepage"><div> |
|---|
| 27 | <div><h2 class="title"> |
|---|
| 28 | <a name="boost_staticassert"></a>Chapter 10. Boost.StaticAssert</h2></div> |
|---|
| 29 | <div><div class="author"><h3 class="author"> |
|---|
| 30 | <span class="firstname">John</span> <span class="surname">Maddock</span> |
|---|
| 31 | </h3></div></div> |
|---|
| 32 | <div><div class="author"><h3 class="author"> |
|---|
| 33 | <span class="firstname">Steve</span> <span class="surname">Cleary</span> |
|---|
| 34 | </h3></div></div> |
|---|
| 35 | <div><p class="copyright">Copyright © 2000, 2005 Steve Cleary and John Maddock</p></div> |
|---|
| 36 | <div><div class="legalnotice"> |
|---|
| 37 | <a name="id2740482"></a><p> |
|---|
| 38 | Distributed under the Boost Software License, Version 1.0. |
|---|
| 39 | (See accompanying file LICENSE_1_0.txt or copy at |
|---|
| 40 | <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top"> |
|---|
| 41 | http://www.boost.org/LICENSE_1_0.txt |
|---|
| 42 | </a>) |
|---|
| 43 | |
|---|
| 44 | </p> |
|---|
| 45 | </div></div> |
|---|
| 46 | </div></div> |
|---|
| 47 | <div class="toc"> |
|---|
| 48 | <p><b>Table of Contents</b></p> |
|---|
| 49 | <dl> |
|---|
| 50 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.intro"> Overview and Tutorial</a></span></dt> |
|---|
| 51 | <dd><dl> |
|---|
| 52 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.namespace"> Use at namespace scope.</a></span></dt> |
|---|
| 53 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.function"> Use at function scope</a></span></dt> |
|---|
| 54 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.class"> Use at class scope</a></span></dt> |
|---|
| 55 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.templates"> Use in templates</a></span></dt> |
|---|
| 56 | </dl></dd> |
|---|
| 57 | <dt><span class="section"><a href="boost_staticassert/how.html"> How it works</a></span></dt> |
|---|
| 58 | <dt><span class="section"><a href="boost_staticassert/test.html"> Test Programs</a></span></dt> |
|---|
| 59 | </dl> |
|---|
| 60 | </div> |
|---|
| 61 | <div class="section" lang="en"> |
|---|
| 62 | <div class="titlepage"><div><div><h3 class="title"> |
|---|
| 63 | <a name="boost_staticassert.intro"></a> Overview and Tutorial</h3></div></div></div> |
|---|
| 64 | <div class="toc"><dl> |
|---|
| 65 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.namespace"> Use at namespace scope.</a></span></dt> |
|---|
| 66 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.function"> Use at function scope</a></span></dt> |
|---|
| 67 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.class"> Use at class scope</a></span></dt> |
|---|
| 68 | <dt><span class="section"><a href="boost_staticassert.html#boost_staticassert.templates"> Use in templates</a></span></dt> |
|---|
| 69 | </dl></div> |
|---|
| 70 | <p> |
|---|
| 71 | The header <code class="computeroutput"><span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span></code> supplies a single macro <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code>, |
|---|
| 72 | which generates a compile time error message if the integral-constant-expression <code class="computeroutput"><span class="identifier">x</span></code> |
|---|
| 73 | is not true. In other words it is the compile time equivalent of the assert macro; |
|---|
| 74 | this is sometimes known as a "compile-time-assertion", but will be called a |
|---|
| 75 | "static assertion" throughout these docs. Note that if the condition is <code class="computeroutput"><span class="keyword">true</span></code>, |
|---|
| 76 | then the macro will generate neither code nor data - and the macro can also |
|---|
| 77 | be used at either namespace, class or function scope. When used in a template, |
|---|
| 78 | the static assertion will be evaluated at the time the template is instantiated; |
|---|
| 79 | this is particularly useful for validating template parameters.</p> |
|---|
| 80 | <p> |
|---|
| 81 | One of the aims of <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code> is to generate readable error messages. |
|---|
| 82 | These immediately tell the user that a library is being used in a manner that |
|---|
| 83 | is not supported. While error messages obviously differ from compiler to compiler, |
|---|
| 84 | but you should see something like:</p> |
|---|
| 85 | <pre class="programlisting"><code class="literal"><span class="identifier">Illegal</span><span class="identifier"> use</span><span class="identifier"> of</span><span class="identifier"> STATIC_ASSERTION_FAILURE</span><span class="special"><</span><span class="keyword">false</span><span class="special">></span></code></pre> |
|---|
| 86 | <p> |
|---|
| 87 | Which is intended to at least catch the eye!</p> |
|---|
| 88 | <p> |
|---|
| 89 | You can use <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code> at any place where you can place a declaration, |
|---|
| 90 | that is at class, function or namespace scope, this is illustrated by the |
|---|
| 91 | following examples:</p> |
|---|
| 92 | <div class="section" lang="en"> |
|---|
| 93 | <div class="titlepage"><div><div><h4 class="title"> |
|---|
| 94 | <a name="boost_staticassert.namespace"></a> Use at namespace scope.</h4></div></div></div> |
|---|
| 95 | <p> |
|---|
| 96 | The macro can be used at namespace scope, if there is some requirement must |
|---|
| 97 | always be true; generally this means some platform specific requirement. |
|---|
| 98 | Suppose we require that <code class="computeroutput"><span class="keyword">int</span></code> be at least a 32-bit integral type, and that <code class="computeroutput"><span class="keyword">wchar_t</span></code> |
|---|
| 99 | be an unsigned type. We can verify this at compile time as follows:</p> |
|---|
| 100 | <pre class="programlisting"><code class="literal"><span class="preprocessor">#include</span><span class="special"> <</span><span class="identifier">climits</span><span class="special">></span><span class="preprocessor"> |
|---|
| 101 | #include</span><span class="special"> <</span><span class="identifier">cwchar</span><span class="special">></span><span class="preprocessor"> |
|---|
| 102 | #include</span><span class="special"> <</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span><span class="keyword"> |
|---|
| 103 | |
|---|
| 104 | namespace</span><span class="identifier"> my_conditions</span><span class="special"> {</span><span class="identifier"> |
|---|
| 105 | |
|---|
| 106 | BOOST_STATIC_ASSERT</span><span class="special">(</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="special"> *</span><span class="identifier"> CHAR_BIT</span><span class="special"> >=</span><span class="number"> 32</span><span class="special">);</span><span class="identifier"> |
|---|
| 107 | BOOST_STATIC_ASSERT</span><span class="special">(</span><span class="identifier">WCHAR_MIN</span><span class="special"> >=</span><span class="number"> 0</span><span class="special">);</span><span class="special"> |
|---|
| 108 | |
|---|
| 109 | }</span><span class="comment"> // namespace my_conditions |
|---|
| 110 | </span></code></pre> |
|---|
| 111 | <p> |
|---|
| 112 | The use of the namespace my_conditions here requires some comment. |
|---|
| 113 | The macro <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code> works by generating an typedef declaration, |
|---|
| 114 | and since the typedef must have a name, the macro generates one automatically by |
|---|
| 115 | mangling a stub name with the value of <span class="underline">_LINE</span>_. When <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code> is |
|---|
| 116 | used at either class or function scope then each use of <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code> |
|---|
| 117 | is guaranteed to produce a name unique to that scope (provided you only use |
|---|
| 118 | the macro once on each line). However when used in a header at namespace |
|---|
| 119 | scope, that namespace can be continued over multiple headers, each of which |
|---|
| 120 | may have their own static assertions, and on the "same" lines, thereby generating |
|---|
| 121 | duplicate declarations. In theory the compiler should silently ignore duplicate |
|---|
| 122 | typedef declarations, however many do not do so (and even if they do they are |
|---|
| 123 | entitled to emit warnings in such cases). To avoid potential problems, if you |
|---|
| 124 | use <code class="computeroutput"><span class="identifier">BOOST_STATIC_ASSERT</span></code> in a header and at namespace scope, then enclose |
|---|
| 125 | them in a namespace unique to that header.</p> |
|---|
| 126 | </div> |
|---|
| 127 | <div class="section" lang="en"> |
|---|
| 128 | <div class="titlepage"><div><div><h4 class="title"> |
|---|
| 129 | <a name="boost_staticassert.function"></a> Use at function scope</h4></div></div></div> |
|---|
| 130 | <p> |
|---|
| 131 | The macro is typically used at function scope inside template functions, |
|---|
| 132 | when the template arguments need checking. Imagine that we have an |
|---|
| 133 | iterator-based algorithm that requires random access iterators. |
|---|
| 134 | If the algorithm is instantiated with iterators that do not meet our |
|---|
| 135 | requirements then an error will be generated eventually, but this may |
|---|
| 136 | be nested deep inside several templates, making it hard for the user to |
|---|
| 137 | determine what went wrong. One option is to add a static assertion at |
|---|
| 138 | the top level of the template, in that case if the condition is not met, |
|---|
| 139 | then an error will be generated in a way that makes it reasonably obvious to |
|---|
| 140 | the user that the template is being misused.</p> |
|---|
| 141 | <pre class="programlisting"><code class="literal"><span class="preprocessor">#include</span><span class="special"> <</span><span class="identifier">iterator</span><span class="special">></span><span class="preprocessor"> |
|---|
| 142 | #include</span><span class="special"> <</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span><span class="preprocessor"> |
|---|
| 143 | #include</span><span class="special"> <</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">type_traits</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span><span class="keyword"> |
|---|
| 144 | |
|---|
| 145 | template</span><span class="special"> <</span><span class="keyword">class</span><span class="identifier"> RandomAccessIterator</span><span class="special"> ></span><span class="identifier"> |
|---|
| 146 | RandomAccessIterator</span><span class="identifier"> foo</span><span class="special">(</span><span class="identifier">RandomAccessIterator</span><span class="identifier"> from</span><span class="special">,</span><span class="identifier"> RandomAccessIterator</span><span class="identifier"> to</span><span class="special">)</span><span class="special"> |
|---|
| 147 | {</span><span class="comment"> |
|---|
| 148 | // this template can only be used with |
|---|
| 149 | // random access iterators... |
|---|
| 150 | </span><span class="keyword"> typedef</span><span class="keyword"> typename</span><span class="identifier"> std</span><span class="special">::</span><span class="identifier">iterator_traits</span><span class="special"><</span><span class="identifier"> RandomAccessIterator</span><span class="special"> >::</span><span class="identifier">iterator_category</span><span class="identifier"> cat</span><span class="special">;</span><span class="identifier"> |
|---|
| 151 | BOOST_STATIC_ASSERT</span><span class="special">((</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">is_convertible</span><span class="special"><</span><span class="identifier">cat</span><span class="special">,</span><span class="keyword"> const</span><span class="identifier"> std</span><span class="special">::</span><span class="identifier">random_access_iterator_tag</span><span class="special">&>::</span><span class="identifier">value</span><span class="special">));</span><span class="comment"> |
|---|
| 152 | // |
|---|
| 153 | // detail goes here... |
|---|
| 154 | </span><span class="keyword"> return</span><span class="identifier"> from</span><span class="special">;</span><span class="special"> |
|---|
| 155 | }</span></code></pre> |
|---|
| 156 | <p> |
|---|
| 157 | A couple of footnotes are in order here: the extra set of parenthesis around the |
|---|
| 158 | assert, is to prevent the comma inside the <code class="computeroutput"><span class="identifier">is_convertible</span></code> template being |
|---|
| 159 | interpreted by the preprocessor as a macro argument separator; the target type |
|---|
| 160 | for <code class="computeroutput"><span class="identifier">is_convertible</span></code> is a reference type, as some compilers have problems |
|---|
| 161 | using <code class="computeroutput"><span class="identifier">is_convertible</span></code> when the conversion is via a user defined constructor |
|---|
| 162 | (in any case there is no guarantee that the iterator tag classes are |
|---|
| 163 | copy-constructible).</p> |
|---|
| 164 | </div> |
|---|
| 165 | <div class="section" lang="en"> |
|---|
| 166 | <div class="titlepage"><div><div><h4 class="title"> |
|---|
| 167 | <a name="boost_staticassert.class"></a> Use at class scope</h4></div></div></div> |
|---|
| 168 | <p> |
|---|
| 169 | The macro is typically used inside classes that are templates. |
|---|
| 170 | Suppose we have a template-class that requires an unsigned integral type with |
|---|
| 171 | at least 16-bits of precision as a template argument, we can achieve this |
|---|
| 172 | using something like this:</p> |
|---|
| 173 | <pre class="programlisting"><code class="literal"><span class="preprocessor">#include</span><span class="special"> <</span><span class="identifier">climits</span><span class="special">></span><span class="preprocessor"> |
|---|
| 174 | #include</span><span class="special"> <</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span><span class="keyword"> |
|---|
| 175 | |
|---|
| 176 | template</span><span class="special"> <</span><span class="keyword">class</span><span class="identifier"> UnsignedInt</span><span class="special">></span><span class="keyword"> |
|---|
| 177 | class</span><span class="identifier"> myclass</span><span class="special"> |
|---|
| 178 | {</span><span class="keyword"> |
|---|
| 179 | private</span><span class="special">:</span><span class="identifier"> |
|---|
| 180 | BOOST_STATIC_ASSERT</span><span class="special">(</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">UnsignedInt</span><span class="special">)</span><span class="special"> *</span><span class="identifier"> CHAR_BIT</span><span class="special"> >=</span><span class="number"> 16</span><span class="special">);</span><span class="identifier"> |
|---|
| 181 | BOOST_STATIC_ASSERT</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">UnsignedInt</span><span class="special">>::</span><span class="identifier">is_specialized</span><span class="special"> |
|---|
| 182 | &&</span><span class="identifier"> std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">UnsignedInt</span><span class="special">>::</span><span class="identifier">is_integer</span><span class="special"> |
|---|
| 183 | &&</span><span class="special"> !</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">UnsignedInt</span><span class="special">>::</span><span class="identifier">is_signed</span><span class="special">);</span><span class="keyword"> |
|---|
| 184 | public</span><span class="special">:</span><span class="comment"> |
|---|
| 185 | /* details here */</span><span class="special"> |
|---|
| 186 | };</span></code></pre> |
|---|
| 187 | </div> |
|---|
| 188 | <div class="section" lang="en"> |
|---|
| 189 | <div class="titlepage"><div><div><h4 class="title"> |
|---|
| 190 | <a name="boost_staticassert.templates"></a> Use in templates</h4></div></div></div> |
|---|
| 191 | <p> |
|---|
| 192 | Normally static assertions when used inside a class or function template, |
|---|
| 193 | will not be instantiated until the template in which it is used is instantiated. |
|---|
| 194 | However, there is one potential problem to watch out for: if the static assertion |
|---|
| 195 | is not dependent upon one or more template parameters, then the compiler is |
|---|
| 196 | permitted to evaluate the static assertion at the point it is first seen, |
|---|
| 197 | irrespective of whether the template is ever instantiated, for example:</p> |
|---|
| 198 | <pre class="programlisting"><code class="literal"><span class="keyword">template</span><span class="special"> <</span><span class="keyword">class</span><span class="identifier"> T</span><span class="special">></span><span class="keyword"> |
|---|
| 199 | struct</span><span class="identifier"> must_not_be_instantiated</span><span class="special"> |
|---|
| 200 | {</span><span class="identifier"> |
|---|
| 201 | BOOST_STATIC_ASSERT</span><span class="special">(</span><span class="keyword">false</span><span class="special">);</span><span class="special"> |
|---|
| 202 | };</span></code></pre> |
|---|
| 203 | <p> |
|---|
| 204 | Will produce a compiler error with some compilers (for example Intel 8.1 |
|---|
| 205 | or gcc 3.4), regardless of whether the template is ever instantiated. A |
|---|
| 206 | workaround in cases like this is to force the assertion to be dependent |
|---|
| 207 | upon a template parameter:</p> |
|---|
| 208 | <pre class="programlisting"><code class="literal"><span class="keyword">template</span><span class="special"> <</span><span class="keyword">class</span><span class="identifier"> T</span><span class="special">></span><span class="keyword"> |
|---|
| 209 | struct</span><span class="identifier"> must_not_be_instantiated</span><span class="special"> |
|---|
| 210 | {</span><span class="comment"> |
|---|
| 211 | // this will be triggered if this type is instantiated |
|---|
| 212 | </span><span class="identifier"> BOOST_STATIC_ASSERT</span><span class="special">(</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span><span class="special"> ==</span><span class="number"> 0</span><span class="special">);</span><span class="special"> |
|---|
| 213 | };</span></code></pre> |
|---|
| 214 | </div> |
|---|
| 215 | </div> |
|---|
| 216 | </div> |
|---|
| 217 | <table width="100%"><tr> |
|---|
| 218 | <td align="left"><small><p>Last revised: April 17, 2005 at 10:45:13 GMT</p></small></td> |
|---|
| 219 | <td align="right"><small></small></td> |
|---|
| 220 | </tr></table> |
|---|
| 221 | <hr> |
|---|
| 222 | <div class="spirit-nav"> |
|---|
| 223 | <a accesskey="p" href="signals/tests.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="boost_staticassert/how.html"><img src="images/next.png" alt="Next"></a> |
|---|
| 224 | </div> |
|---|
| 225 | </body> |
|---|
| 226 | </html> |
|---|
