mirror of
https://github.com/boostorg/pool.git
synced 2026-01-23 17:52:15 +00:00
129 lines
6.3 KiB
HTML
129 lines
6.3 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>postulate - Compile-Time Assertion</TITLE>
|
|
<LINK HREF="../pool.css" REL="stylesheet" TYPE="text/css">
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<IMG SRC="../../../../c++boost.gif" WIDTH=276 HEIGHT=86 ALT="C++ Boost">
|
|
|
|
<H1 ALIGN=CENTER>postulate - Compile-Time Assertion</H1>
|
|
|
|
<P>
|
|
<H2>Introduction</H2>
|
|
|
|
<P>
|
|
detail/postulate.hpp provides a macro that can be used to test compile-time boolean conditions. This macro, <SPAN CLASS="code">BOOST_POOL_POSTULATE</SPAN>, takes one parameter, which is the condition to test. It will fail to compile if that condition is false. Any integral constant expression <A HREF="#5.19/1"><SUP>[5.19/1]</SUP></A> may be used as the condition, which includes expressions dependent on template arguments.
|
|
|
|
<P>
|
|
<SPAN CLASS="code">BOOST_POOL_POSTULATE</SPAN> may be used at namespace scope, class scope, or function scope. It may <STRONG>not</STRONG> be used anywhere else; for example, inside of parameter lists. For templates, the postulate is tested when the template is instantiated. It may not be used more than once per line; multiple tests must be placed on separate lines.
|
|
|
|
<P>
|
|
If the condition is false, the compiler will trigger an error at the place where the postulate macro is used. For this reason, it is often suggested that a comment be placed on the line before the postulate to explain why it is necessary.
|
|
|
|
<P>
|
|
This file also provides a macro, <SPAN CLASS="code">BOOST_POOL_JOIN</SPAN>, which merges two preprocessor tokens <STRONG>after</STRONG> macro substitution. (The <SPAN CLASS="code">##</SPAN> preprocessor operator merges them <STRONG>before</STRONG> macro substitution).
|
|
|
|
<P>
|
|
<H2>Examples</H2>
|
|
|
|
<P>
|
|
One of the simplest examples is to ensure that we are running on a 32-bit platform:
|
|
<PRE CLASS="code">// This code is only valid on a 32-bit platform
|
|
BOOST_POOL_POSTULATE(sizeof(int) * CHAR_BIT == 32);</PRE>
|
|
|
|
<P>
|
|
Or, for more portable code, to ensure that we are running on a 2's complement platform:
|
|
<PRE CLASS="code">// This code must run on a 2's complement platform
|
|
BOOST_POOL_POSTULATE(~1 + 1 == -1);</PRE>
|
|
|
|
<P>
|
|
More complicated usage allows arbitrary restrictions on template arguments:
|
|
<PRE CLASS="code">template <int x, int y>
|
|
struct EmmaWoodhouse
|
|
{
|
|
// The following tests are not actually tested until
|
|
// EmmaWoodhouse<X, Y> is instantiated for some X and Y
|
|
|
|
// x has to be >= 13 because . . .
|
|
BOOST_POOL_POSTULATE(x >= 13);
|
|
|
|
// y has to be > x because . . .
|
|
BOOST_POOL_POSTULATE(y > x);
|
|
. . .
|
|
};</PRE>
|
|
|
|
<P>
|
|
<H2>Symbols</H2>
|
|
|
|
<P>
|
|
<UL>
|
|
<LI>BOOST_POOL_POSTULATE (macro)</LI>
|
|
<LI>BOOST_POOL_JOIN (macro)</LI>
|
|
</UL>
|
|
|
|
<P>
|
|
<H2>Notes</H2>
|
|
|
|
<P>
|
|
No compile-time assertion mechanism is perfect. However, each one should attempt to satisfy the following requirements:
|
|
<OL>
|
|
<LI>Basics
|
|
<DL>
|
|
<DT>Can use compile-time constants<DD>It can use anything that the compiler can figure out at compile time, using the same rules as those for array sizes, not the more restrictive rules of the preprocessor.
|
|
<DT>Stop with error<DD>With a false expression it will prevent the program from compiling, causing an an error.
|
|
<DT>Portable<DD>It will work on any conforming compiler (uses only things in the standard).
|
|
<DT>Practical<DD>It will work on currently available compilers.
|
|
<DT>Efficient<DD>No real code should be generated and no storage should be used. Using it has no cost or effect on the program other than preventing it from compiling -- it doesn't change optimizations, sizes of structures, or anything like that.
|
|
</DL></LI><LI>Error Message
|
|
<DL>
|
|
<DT>Error on correct line<DD>Give an error message <STRONG>at the line</STRONG> where the assertion fails. The line that the compiler reports an error on will be the line of the assertion statement.
|
|
<DT>Good error message<DD>The error message will be easy to understand on any compiler.
|
|
</DL></LI><LI>Usage
|
|
<DL>
|
|
<DT>Universal syntax<DD>Usable in both declarations and implementations in the same way. It can be used inside a function definition or outside a function definition, inside a class declaration or outside a class declaration.
|
|
<DT>Simple syntax<DD>It can be called in a simple way, similar to assert.
|
|
<DT>Robust syntax<DD>Won't silently fail on simple coding errors.
|
|
</DL></LI><LI>Namespace pollution
|
|
<DL>
|
|
<DT>Minimal pollution<DD>Scopes should be polluted in a minimal way.
|
|
<DT>Macro avoidance<DD>Since macros pollute <STRONG>every</STRONG> scope, they should be avoided.
|
|
</DL></LI></OL>
|
|
|
|
<P>
|
|
The search for a good compile-time postulate has been going on for years. This solution is the result of the combined effort of at least: John Maddock, Darin Adler, Jay Zipnick, Beman Dawes, and Csaba Szepesvari. In particular, John Maddock was the person who first formulated this particular solution; whereas Csaba Szepesvari, Darin Adler, and Beman Dawes are responsible for the requirements. Jay Zipnick is responsible for the name "postualte."
|
|
|
|
<P>
|
|
<H2>Dependencies</H2>
|
|
|
|
<P>
|
|
None.
|
|
|
|
<P>
|
|
<H2>Selected Quotations from the Standard</H2>
|
|
|
|
<P>
|
|
<A NAME="5.19/1">
|
|
<STRONG>5.19/1: Expressions: Constant Expressions:</STRONG> ". . . An <EM>integral constant expression</EM> can involve only literals (2.13), enumerators, <SPAN CLASS="code">const</SPAN> variables or static data members of integral or enumeration types initialized with constant expressions (8.5), non-type template parameters of integral or enumeration types, and <SPAN CLASS="code">sizeof</SPAN> expressions. Floating literals (2.13.3) can appear only if they are cast to integral or enumeration types. Only type conversions to integral or enumeration types can be used. In particular, except in <SPAN CLASS="code">sizeof</SPAN> expressions, functions, class objects, pointers, or references shall not be used, and assignment, increment, decrement, function-call, or comma operators shall not be used."</A>
|
|
|
|
<P>
|
|
<H2>Future Directions</H2>
|
|
|
|
<P>
|
|
This header will soon be replaced by the Boost static assert library.
|
|
|
|
<P>
|
|
<HR>
|
|
|
|
<P>
|
|
Copyright © 2000, 2001 Stephen Cleary (<A HREF="mailto:shammah@voyager.net">shammah@voyager.net</A>)
|
|
|
|
<P>
|
|
This file can be redistributed and/or modified under the terms found in <A HREF="../copyright.html">copyright.html</A>
|
|
|
|
<P>
|
|
This software and its documentation is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.
|
|
|
|
</BODY>
|
|
</HTML> |