<aname="boost_config.static_assert.intro"></a><aclass="link"href="static_assert.html#boost_config.static_assert.intro"title="Overview and Tutorial">Overview and Tutorial</a>
</h3></div></div></div>
<divclass="toc"><dlclass="toc">
<dt><spanclass="section"><ahref="static_assert.html#boost_config.static_assert.intro.namespace">Use at
namespace scope</a></span></dt>
<dt><spanclass="section"><ahref="static_assert.html#boost_config.static_assert.intro.function">Use at function
scope</a></span></dt>
<dt><spanclass="section"><ahref="static_assert.html#boost_config.static_assert.intro.class">Use at class
scope</a></span></dt>
<dt><spanclass="section"><ahref="static_assert.html#boost_config.static_assert.intro.templates">Use in
templates</a></span></dt>
</dl></div>
<p>
The header <codeclass="computeroutput"><spanclass="special"><</span><spanclass="identifier">boost</span><spanclass="special">/</span><spanclass="keyword">static_assert</span><spanclass="special">.</span><spanclass="identifier">hpp</span><spanclass="special">></span></code>
Both generate a compile time error message if the integral-constant-expression
<codeclass="computeroutput"><spanclass="identifier">x</span></code> is not true. In other words,
they are 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 <codeclass="computeroutput"><spanclass="keyword">true</span></code>, then the macros will generate neither
code nor data - and the macros 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.
</p>
<p>
If the C++0x <codeclass="computeroutput"><spanclass="keyword">static_assert</span></code> feature
is available, both macros will use it. For <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span><spanclass="special">(</span><spanclass="identifier">x</span><spanclass="special">)</span></code>,
the error message will be a stringized version of <codeclass="computeroutput"><spanclass="identifier">x</span></code>.
For <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT_MSG</span><spanclass="special">(</span><spanclass="identifier">x</span><spanclass="special">,</span>
the error message will be the <codeclass="computeroutput"><spanclass="identifier">msg</span></code>
string.
</p>
<p>
If the C++0x <codeclass="computeroutput"><spanclass="keyword">static_assert</span></code> feature
is not available, <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT_MSG</span><spanclass="special">(</span><spanclass="identifier">x</span><spanclass="special">,</span>
will be treated as <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span><spanclass="special">(</span><spanclass="identifier">x</span><spanclass="special">)</span></code>.
</p>
<p>
The material that follows assumes the C++0x <codeclass="computeroutput"><spanclass="keyword">static_assert</span></code>
feature is not available.
</p>
<p>
One of the aims of <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span></code>
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
You can use <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span></code>
at any place where you can place a declaration, that is at class, function
or namespace scope, this is illustrated by the following examples:
</p>
<divclass="section">
<divclass="titlepage"><div><div><h4class="title">
<aname="boost_config.static_assert.intro.namespace"></a><aclass="link"href="static_assert.html#boost_config.static_assert.intro.namespace"title="Use at namespace scope">Use at
namespace scope</a>
</h4></div></div></div>
<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 <codeclass="computeroutput"><spanclass="keyword">int</span></code>
be at least a 32-bit integral type, and that <codeclass="computeroutput"><spanclass="keyword">wchar_t</span></code>
be an unsigned type. We can verify this at compile time as follows:
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 <codeclass="computeroutput"><spanclass="identifier">__LINE__</span></code>.
When <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span></code>
is used at either class or function scope then each use of <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span></code> 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 <codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span></code>
in a header and at namespace scope, then enclose them in a namespace unique
to that header.
</p>
</div>
<divclass="section">
<divclass="titlepage"><div><div><h4class="title">
<aname="boost_config.static_assert.intro.function"></a><aclass="link"href="static_assert.html#boost_config.static_assert.intro.function"title="Use at function scope">Use at function
scope</a>
</h4></div></div></div>
<p>
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.
A couple of footnotes are in order here: the extra set of parenthesis around
the assert, is to prevent the comma inside the <codeclass="computeroutput"><spanclass="identifier">is_convertible</span></code>
template being interpreted by the preprocessor as a macro argument separator;
the target type for <codeclass="computeroutput"><spanclass="identifier">is_convertible</span></code>
is a reference type, as some compilers have problems using <codeclass="computeroutput"><spanclass="identifier">is_convertible</span></code> when the conversion is
via a user defined constructor (in any case there is no guarantee that
the iterator tag classes are copy-constructible).
</p>
</div>
<divclass="section">
<divclass="titlepage"><div><div><h4class="title">
<aname="boost_config.static_assert.intro.class"></a><aclass="link"href="static_assert.html#boost_config.static_assert.intro.class"title="Use at class scope">Use at class
scope</a>
</h4></div></div></div>
<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 of precision as a template argument, we can achieve this
<spanclass="identifier">BOOST_STATIC_ASSERT_MSG</span><spanclass="special">(</span><spanclass="identifier">std</span><spanclass="special">::</span><spanclass="identifier">numeric_limits</span><spanclass="special"><</span><spanclass="identifier">UnsignedInt</span><spanclass="special">>::</span><spanclass="identifier">is_specialized</span><spanclass="special">,</span><spanclass="string">"myclass can only be specialized for types with numeric_limits support."</span><spanclass="special">);</span>
<spanclass="identifier">BOOST_STATIC_ASSERT_MSG</span><spanclass="special">(</span><spanclass="identifier">std</span><spanclass="special">::</span><spanclass="identifier">numeric_limits</span><spanclass="special"><</span><spanclass="identifier">UnsignedInt</span><spanclass="special">>::</span><spanclass="identifier">digits</span><spanclass="special">>=</span><spanclass="number">16</span><spanclass="special">,</span><spanclass="string">"Template argument UnsignedInt must have at least 16 bits precision."</span><spanclass="special">)</span>
<spanclass="identifier">BOOST_STATIC_ASSERT_MSG</span><spanclass="special">(</span><spanclass="identifier">std</span><spanclass="special">::</span><spanclass="identifier">numeric_limits</span><spanclass="special"><</span><spanclass="identifier">UnsignedInt</span><spanclass="special">>::</span><spanclass="identifier">is_integer</span><spanclass="special">,</span><spanclass="string">"Template argument UnsignedInt must be an integer."</span><spanclass="special">);</span>
<spanclass="identifier">BOOST_STATIC_ASSERT_MSG</span><spanclass="special">(!</span><spanclass="identifier">std</span><spanclass="special">::</span><spanclass="identifier">numeric_limits</span><spanclass="special"><</span><spanclass="identifier">UnsignedInt</span><spanclass="special">>::</span><spanclass="identifier">is_signed</span><spanclass="special">,</span><spanclass="string">"Template argument UnsignedInt must not be signed."</span><spanclass="special">);</span>
<aname="boost_config.static_assert.intro.templates"></a><aclass="link"href="static_assert.html#boost_config.static_assert.intro.templates"title="Use in templates">Use in
templates</a>
</h4></div></div></div>
<p>
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,
<aname="boost_config.static_assert.how"></a><aclass="link"href="static_assert.html#boost_config.static_assert.how"title="How it works">How it works</a>
</h3></div></div></div>
<p>
<codeclass="computeroutput"><spanclass="identifier">BOOST_STATIC_ASSERT</span></code> works
as follows. There is class <codeclass="computeroutput"><spanclass="identifier">STATIC_ASSERTION_FAILURE</span></code>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Andrey Semashev