<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html
lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="content-type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
<title>Appendix A - An Introduction to Preprocessor Metaprogramming</title>
<meta name="copyright" content="From "C++ Template Metaprogramming," by David Abrahams and Aleksey Gurtovoy. Copyright (c) 2005 by Pearson Education, Inc. Reprinted with permission." />
<style type="text/css">
.first {
margin-top: 0 }
.last {
margin-bottom: 0 }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.attention, div.caution, div.danger, div.error, div.hint,
div.important, div.note, div.tip, div.warning, div.admonition {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
div.hint p.admonition-title, div.important p.admonition-title,
div.note p.admonition-title, div.tip p.admonition-title,
div.admonition p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr {
width: 75% }
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font-family: serif ;
font-size: 100% }
pre.line-block {
font-family: serif ;
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
background-color: #eeeeee }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.option-argument {
font-style: italic }
span.pre {
white-space: pre }
span.problematic {
color: red }
table {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.citation {
border-left: solid thin gray ;
padding-left: 0.5ex }
table.docinfo {
margin: 2em 4em }
table.footnote {
border-left: solid thin black ;
padding-left: 0.5ex }
dt {
font-weight: bold }
td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap }
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
tt {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style> </head>
<body><br />
<div class="document" id="preprocessor-title">
<h1 class="title">Appendix A - An Introduction to Preprocessor
Metaprogramming</h1>
<table class="docinfo" frame="void" rules="none">
<colgroup><col class="docinfo-name" /> <col class="docinfo-content" />
</colgroup>
<tbody valign="top">
<tr>
<th class="docinfo-name">Copyright:</th>
<td>From "C++ Template Metaprogramming," by David Abrahams and
Aleksey Gurtovoy. Copyright (c) 2005 by Pearson Education, Inc.
Reprinted with permission.</td>
</tr>
<tr class="field">
<th class="docinfo-name">ISBN:</th>
<td class="field-body">0321227255</td>
</tr>
</tbody>
</table>
<div class="section" id="motivation">
<h1><a name="motivation">A.1 Motivation</a></h1>
<p>Even with the full power of template metaprogramming and the <a class="reference"
href="http://www.boost.org/libs/mpl">Boost Metaprogramming library</a>
at our disposal, some C++ coding jobs still require a great deal of
boilerplate code repetition. We saw one example in Chapter 5, when we
implemented <tt class="docutils literal"><span class="pre">tiny_size</span></tt>:</p>
<pre class="literal-block">template <class T0, class T1, class T2>
struct tiny_size
: mpl::int_<3> {};
</pre>
<p>Aside from the repeated pattern in the parameter list of the primary
template above, there are three partial specializations below, which
also follow a predictable pattern:</p>
<pre class="literal-block">template <class T0, class T1>
struct tiny_size<T0,T1,none>
: mpl::int_<2> {};
template <class T0>
struct tiny_size<T0,none,none>
: mpl::int_<1> {};
template <>
struct tiny_size<none,none,none>
: mpl::int_<0> {};
</pre>
<p>In this case there is only a small amount of code with such a
"mechanical" flavor, but had we been implementing <tt class="docutils literal"><span
class="pre">large</span></tt> instead of <tt class="docutils literal"><span
class="pre">tiny</span></tt>, there might easily have been a great
deal more. When the number of instances of a pattern grows beyond two
or three, writing them by hand tends to become error-prone. Perhaps
more importantly, the code gets hard to read, because the important
abstraction in the code is really the pattern, not the individual
instances.</p>
<div class="section" id="code-generation">
<h2><a name="code-generation">A.1.1 Code Generation</a></h2>
<p>Rather than being written out by hand, mechanical-looking code
should really be generated mechanically. Having written a program to
spit out instances of the code pattern, a library author has two
choices: She can either ship pre-generated source code files, or she
can ship the generator itself. Either approach has drawbacks. If
clients only get the generated source, they are stuck with whatever
the library author generated—and experience shows that if they are
happy with three instances of a pattern today, someone will need
four tomorrow. If clients get the generator program, on the other
hand, they also need the resources to execute it (e.g.,
interpreters), and they must integrate the generator into their
build processes...</p>
</div>
<div class="section" id="enter-the-preprocessor">
<h2><a name="enter-the-preprocessor">A.1.2 Enter the Preprocessor</a></h2>
<p>...unless the generator is a preprocessor metaprogram. Though not
designed for that purpose, the C and C++ preprocessors can be made
to execute sophisticated programs during the preprocessing phase of
compilation. Users can control the code generation process with
preprocessor <tt class="docutils literal"><span class="pre">#define</span></tt>s
in code or <tt class="docutils literal"><span class="pre">-D</span></tt>
options on the compiler's command line, making build integration
trivial. For example, we might parameterize the primary <tt class="docutils literal"><span
class="pre">tiny_size</span></tt> template above as follows:</p>
<pre class="literal-block">#include <<strong>boost/preprocessor/repetition/enum_params</strong>.hpp>
#ifndef TINY_MAX_SIZE
# define TINY_MAX_SIZE 3 // default maximum size is 3
#endif
template <<strong>BOOST_PP_ENUM_PARAMS(TINY_MAX_SIZE, class T)</strong>>
struct tiny_size
: mpl::int_<TINY_MAX_SIZE>
{};
</pre>
<p>To test the metaprogram, run your compiler in its "preprocessing"
mode (usually the <tt class="docutils literal"><span class="pre">-E</span></tt>
option), with the Boost root directory in your <tt class="docutils literal"><span
class="pre">#include</span></tt> path. For instance:<a class="footnote-reference"
href="#minusp" id="id2" name="id2">[1]</a></p>
<pre class="literal-block">g++ -P -E -Ipath/to/boost_1_32_0 -I. test.cpp
</pre>
<table class="docutils footnote" frame="void" id="minusp" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id2" name="minusp">[1]</a></td>
<td>GCC's <tt class="docutils literal"><span class="pre">-P</span></tt>
option inhibits the generation of source file and line number
markers in preprocessed output.</td>
</tr>
</tbody>
</table>
<p>Given the appropriate metaprograms, users would be able to adjust
not only the number of parameters to <tt class="docutils literal"><span
class="pre">tiny_size</span></tt>, but the maximum size of the
entire <tt class="docutils literal"><span class="pre">tiny</span></tt>
implementation just by <tt class="docutils literal"><span class="pre">#define</span></tt>-ing
<tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>.</p>
<p>The Boost Preprocessor library <a class="citation-reference" href="#mk04"
id="id3" name="id3">[MK04]</a> plays a role in preprocessor
metaprogramming similar to the one played by the MPL in template
metaprogramming: It supplies a framework of high-level components
(like <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>)
that make otherwise-painful metaprogramming jobs approachable. In
this appendix we won't attempt to cover nitty-gritty details of how
the preprocessor works, nor principles of preprocessor
metaprogramming in general, nor even many details of how the
Preprocessor <em>library</em> works. We <em>will</em> show you
enough at a high level that you'll be able to use the library
productively and learn the rest on your own.</p>
<table class="docutils citation" frame="void" id="mk04" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id3" name="mk04">[MK04]</a></td>
<td>Paul Mensonides and Vesa Karvonen. "The Boost Preprocessor
Library." <a class="reference" href="http://www.boost.org/libs/preprocessor">http://www.boost.org/libs/preprocessor</a>.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="fundamental-abstractions-of-the-preprocessor">
<h1><a name="fundamental-abstractions-of-the-preprocessor">A.2 Fundamental
Abstractions of the Preprocessor</a></h1>
<p>We began our discussion of template metaprogramming in Chapter 2 by
describing its metadata (potential template arguments) and
metafunctions (class templates). On the basis of those two fundamental
abstractions, we built up the entire picture of compile-time
computation covered in the rest of this book. In this section we'll
lay a similar foundation for the preprocessor metaprogrammer. Some of
what we cover here may be a review for you, but it's important to
identify the basic concepts going into detail.</p>
<div class="section" id="preprocessing-tokens">
<h2><a name="preprocessing-tokens">A.2.1 Preprocessing Tokens</a></h2>
<p>The fundamental unit of data in the preprocessor is the <strong>preprocessing
token</strong>. Preprocessing tokens correspond roughly to the
tokens you're used to working with in C++, such as identifiers,
operator symbols, and literals. Technically, there are some
differences between <em>preprocessing tokens</em> and regular <em>tokens</em>
(see section 2 of the C++ standard for details), but they can be
ignored for the purposes of this discussion. In fact, we'll be using
the terms interchangeably here.</p>
</div>
<div class="section" id="macros">
<h2><a name="macros">A.2.2 Macros</a></h2>
<p>Preprocessor macros come in two flavors. <strong>Object-like
macros</strong> can be defined this way:</p>
<blockquote>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">#define</span></tt>
<em>identifier</em> <em>replacement-list</em></div>
</div>
</blockquote>
<p>where the <em>identifier</em> names the macro being defined, and <em>replacement-list</em>
is a sequence of zero or more tokens. Where the <em>identifier</em>
appears in subsequent program text, it is <strong>expanded</strong>
by the preprocessor into its <em>replacement-list</em>.</p>
<p><strong>Function-like macros</strong>, which act as the
"metafunctions of the preprocessing phase," are defined as follows:</p>
<blockquote>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">#define</span></tt>
<em>identifier</em>(<em>a</em><sub>1</sub>, <em>a</em><sub>2</sub>,
... <em>a</em><sub>n</sub>) <em>replacement-list</em></div>
</div>
</blockquote>
<p>where each <em>a</em><sub>i</sub> is an identifier naming a <strong>macro
parameter</strong>. When the macro name appears in subsequent
program text followed by a suitable argument list, it is expanded
into its <em>replacement-list</em>, except that each argument is
substituted for the corresponding parameter where it appears in the
<em>replacement-list</em>.<a class="footnote-reference" href="#expansion"
id="id4" name="id4">[2]</a></p>
<table class="docutils footnote" frame="void" id="expansion" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id4" name="expansion">[2]</a></td>
<td>We have omitted many details of how macro expansion works.
We encourage you to take a few minutes to study section 16.3
of the C++ standard, which describes that process in
straightforward terms.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="macro-arguments">
<h2><a name="macro-arguments">A.2.3 Macro Arguments</a></h2>
<div class="admonition-definition admonition">
<p class="first admonition-title">Definition</p>
<p>A <strong>macro argument</strong> is a nonempty sequence of:</p>
<ul class="last simple">
<li>Preprocessing tokens other than commas or parentheses, <em>and/or</em></li>
<li>Preprocessing tokens surrounded by matched pairs of
parentheses.</li>
</ul>
</div>
<p>This definition has consequences for preprocessor metaprogramming
that must not be underestimated. Note, first of all, that the
following tokens have special status:</p>
<blockquote>
<pre class="literal-block">, ( )
</pre> </blockquote>
<p>As a result, a macro argument can never contain an unmatched
parenthesis, or a comma that is not surrounded by matched
parentheses. For example, both lines following the definition of FOO
below are ill-formed:</p>
<pre class="literal-block">#define FOO(X) X // Unary identity macro
FOO(,) // un-parenthesized comma or two empty arguments
FOO()) // unmatched parenthesis or missing argument
</pre>
<p>Note also that the following tokens do <em>not</em> have special
status; the preprocessor knows nothing about matched pairs of
braces, brackets, or angle brackets:</p>
<blockquote>
<pre class="literal-block">{ } [ ] < >
</pre> </blockquote>
<p>As a result, these lines are also ill-formed:</p>
<pre class="literal-block">FOO(std::pair<int<strong>,</strong> long>) // two arguments
FOO({ int x = 1<strong>,</strong> y = 2; return x+y; }) // two arguments
</pre>
<p>It <em>is</em> possible to pass either string of tokens above as
part of a single macro argument, provided it is parenthesized:</p>
<pre class="literal-block">FOO(<strong>(</strong>std::pair<int,int><strong>)</strong>) // one argument
FOO(<strong>(</strong>{ int x = 1, y = 2; return x+y; }<strong>)</strong>) // one argument
</pre>
<p>However, because of the special status of commas, it is impossible
to strip parentheses from a macro argument without knowing the
number of comma-separated token sequences it contains.<a class="footnote-reference"
href="#c99" id="id5" name="id5">[3]</a> If you are writing a macro
that needs to be able to accept an argument containing a variable
number of commas, your users will either have to parenthesize that
argument <em>and</em> pass you the number of comma-separated token
sequences as an additional argument, or they will have to encode the
same information in one of the preprocessor data structures covered
later in this appendix.</p>
<table class="docutils footnote" frame="void" id="c99" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a name="c99">[3]</a></td>
<td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref"
href="#id12">2</a>)</em> The C99 preprocessor, by virtue
of its variadic macros, can do that and more. The C++
standardization committee is likely to adopt C99's
preprocessor extensions for the next version of the C++
standard.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="preprocessor-library-structure">
<h1><a name="preprocessor-library-structure">A.3 Preprocessor Library
Structure</a></h1>
<p>Since in-depth coverage of the Boost Preprocessor library is beyond
the scope of this book, we'll try to give you the <em>tools</em> to
gain an in-depth understanding of the library here. To do that, you'll
need to use the electronic Preprocessor library documentation, which
begins with the index.html file in the <tt class="docutils literal"><span
class="pre">libs/preprocessor/</span></tt> subdirectory of your
Boost installation.</p>
<p>On the left of your browser window you'll see an index, and if you
follow the "Headers" link, it will reveal the structure of the <tt class="docutils literal"><span
class="pre">boost/preprocessor/</span></tt> directory. Most of the
library's headers are grouped into subdirectories according to related
functionality. The top-level directory contains only a few headers
that provide general-purpose macros, along with a header for each
subdirectory that simply <tt class="docutils literal"><span class="pre">#include</span></tt>s
all the headers in that subdirectory. For example, <tt class="docutils literal"><span
class="pre">boost/preprocessor/selection.hpp</span></tt> does
nothing more than to <tt class="docutils literal"><span class="pre">#include</span></tt>
the <tt class="docutils literal"><span class="pre">min.hpp</span></tt>
and <tt class="docutils literal"><span class="pre">max.hpp</span></tt>
headers that comprise the contents of <tt class="docutils literal"><span
class="pre">boost/preprocessor/selection/</span></tt>. The headers
whose names <em>don't</em> correspond to subdirectories generally
declare a macro whose name is the same as the name of the header,
without the extension, and with a <tt class="docutils literal"><span
class="pre">BOOST_PP_</span></tt> prefix. For example, <tt class="docutils literal"><span
class="pre">boost/preprocessor/selection/max.hpp</span></tt>
declares <tt class="docutils literal"><span class="pre">BOOST_PP_MAX</span></tt>.</p>
<p>You'll also notice that often a header will declare an additional
macro with a <tt class="docutils literal"><span class="pre">_D</span></tt>,
<tt class="docutils literal"><span class="pre">_R</span></tt>, or <tt
class="docutils literal"><span class="pre">_Z</span></tt> suffix.<a
class="footnote-reference" href="#suffix" id="id6" name="id6">[4]</a>
For instance, <tt class="docutils literal"><span class="pre">boost/preprocessor/selection/max.hpp</span></tt>
also declares <tt class="docutils literal"><span class="pre">BOOST_PP_MAX_D</span></tt>.
For the purposes of this appendix, you should ignore those macros.
Eventually you will want to understand how they can be used to
optimize preprocessing speed; consult the Topics section of the
library documentation under the subheading "reentrancy" for that
information.</p>
<table class="docutils footnote" frame="void" id="suffix" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id6" name="suffix">[4]</a></td>
<td>Macros with <tt class="docutils literal"><span class="pre">_1ST</span></tt>,
<tt class="docutils literal"><span class="pre">_2ND</span></tt>,
or <tt class="docutils literal"><span class="pre">_3RD</span></tt>
suffixes, if they appear, should be ignored for a different
reason: They are deprecated and will be removed from the library
soon.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="preprocessor-library-abstractions">
<h1><a name="preprocessor-library-abstractions">A.4 Preprocessor
Library Abstractions</a></h1>
<p>In this section we'll discuss the basic abstractions of the
Preprocessor library, and give some simple examples of each.</p>
<div class="section" id="repetition">
<h2><a name="repetition">A.4.1 Repetition</a></h2>
<p>The repeated generation of <tt class="docutils literal"><span class="pre">class</span>
<span class="pre">T0</span></tt>, <tt class="docutils literal"><span
class="pre">class</span> <span class="pre">T1</span></tt>... <tt
class="docutils literal"><span class="pre">class</span> <span class="pre">T</span></tt><em>n</em>
that we achieved using <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>
was a specific case of the general concept of <strong>horizontal
repetition</strong>. The library also has a concept of vertical
repetition, which we'll get to in a moment. Horizontal repetition
macros are all found in the library's <tt class="docutils literal"><span
class="pre">repetition/</span></tt> subdirectory.</p>
<div class="section" id="horizontal-repetition">
<h3><a name="horizontal-repetition">A.4.1.1 Horizontal Repetition</a></h3>
<p>To generate the <tt class="docutils literal"><span class="pre">tiny_size</span></tt>
specializations using horizontal repetition, we might write the
following:</p>
<pre class="literal-block">#include <boost/preprocessor/repetition.hpp>
#include <boost/preprocessor/arithmetic/sub.hpp>
#include <boost/preprocessor/punctuation/comma_if.hpp>
#define TINY_print(z, n, data) data
#define TINY_size(z, n, unused) \
template <BOOST_PP_ENUM_PARAMS(n, class T)> \
struct tiny_size< \
BOOST_PP_ENUM_PARAMS(n,T) \
BOOST_PP_COMMA_IF(n) \
BOOST_PP_ENUM( \
BOOST_PP_SUB(TINY_MAX_SIZE,n), TINY_print, none) \
> \
: mpl::int_<n> {};
BOOST_PP_REPEAT(TINY_MAX_SIZE, TINY_size, ~)
#undef TINY_size
#undef TINY_print
</pre>
<p>The code generation process is kicked off by calling <tt class="docutils literal"><span
class="pre">BOOST_PP_REPEAT</span></tt>, a <strong>higher-order
macro</strong> that repeatedly invokes the macro named by its
second argument (<tt class="docutils literal"><span class="pre">TINY_size</span></tt>).
The first argument specifies the number of repeated invocations,
and the third one can be any data; it is passed on unchanged to
the macro being invoked. In this case, <tt class="docutils literal"><span
class="pre">TINY_size</span></tt> doesn't use that data, so
the choice to pass <tt class="docutils literal"><span class="pre">~</span></tt>
was arbitrary.<a class="footnote-reference" href="#markers" id="id7"
name="id7">[5]</a></p>
<table class="docutils footnote" frame="void" id="markers" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id7" name="markers">[5]</a></td>
<td><tt class="docutils literal"><span class="pre">~</span></tt>
is not an <em>entirely</em> arbitrary choice. Both <tt class="docutils literal"><span
class="pre">@</span></tt> and <tt class="docutils literal"><span
class="pre">$</span></tt> might have been good choices,
except that they are technically not part of the basic
character set that C++ implementations are required to
support. An identifier like <tt class="docutils literal"><span
class="pre">ignored</span></tt> might be subject to
macro expansion, leading to unexpected results.</td>
</tr>
</tbody>
</table>
<p>Each time the <tt class="docutils literal"><span class="pre">TINY_size</span></tt>
macro is invoked by <tt class="docutils literal"><span class="pre">BOOST_PP_REPEAT</span></tt>,
it generates a different specialization of <tt class="docutils literal"><span
class="pre">tiny_size</span></tt>. The macro accepts three
parameters.</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">z</span></tt>
is related to the <tt class="docutils literal"><span class="pre">_Z</span></tt>
macro suffix we mentioned earlier. You'll never need to use it
except for optimization purposes, and can safely ignore it for
now.</li>
<li><tt class="docutils literal"><span class="pre">n</span></tt>
is the repetition index. In repeated invocations of <tt class="docutils literal"><span
class="pre">TINY_size</span></tt>, <tt class="docutils literal"><span
class="pre">n</span></tt> will be <tt class="docutils literal"><span
class="pre">0</span></tt>, then <tt class="docutils literal"><span
class="pre">1</span></tt>, then <tt class="docutils literal"><span
class="pre">2</span></tt>, and so on.</li>
<li><tt class="docutils literal"><span class="pre">unused</span></tt>,
in this case, will be <tt class="docutils literal"><span class="pre">~</span></tt>
on each repetition. In general, the final argument to a macro
invoked by <tt class="docutils literal"><span class="pre">BOOST_PP_REPEAT</span></tt>
is always the same as its invoker's final argument.</li>
</ul>
<p>Because its <em>replacement-list</em> covers several lines, all
but the last line of <tt class="docutils literal"><span class="pre">TINY_size</span></tt>
is continued with a trailing backslash. The first few of those
lines just invoke <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>
(which we already used in the primary template) to generate
comma-separated lists, so each invocation of <tt class="docutils literal"><span
class="pre">TINY_size</span></tt> produces something
equivalent to:<a class="footnote-reference" href="#cont" id="id8"
name="id8">[6]</a></p>
<pre class="literal-block">template <<strong>class T0, class T1, ... class T</strong><em>n-1</em>>
struct tiny_size<
<strong>T0, T1, ... T</strong><em>n-1</em>
<em>...more...</em>
>
: mpl::int_<n> {};
</pre>
<table class="docutils footnote" frame="void" id="cont" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id8" name="cont">[6]</a></td>
<td>Note that the line continuation characters <em>and</em>
the newlines following them are removed by the preprocessor,
so the resulting code actually appears on a single line in
the preprocessed output.</td>
</tr>
</tbody>
</table>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_COMMA_IF</span></tt>
generates a comma if its numeric argument is not <tt class="docutils literal"><span
class="pre">0</span></tt>. When <tt class="docutils literal"><span
class="pre">n</span></tt> is <tt class="docutils literal"><span
class="pre">0</span></tt>, the list generated by the preceding
line will be empty, and a leading comma directly following the <tt
class="docutils literal"><span class="pre"><</span></tt>
character would be ill-formed.</p>
<p>The next line uses <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>
to generate <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE-n</span></tt>
comma-separated copies of <tt class="docutils literal"><span class="pre">none</span></tt>.
<tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>
is just like <tt class="docutils literal"><span class="pre">BOOST_PP_REPEAT</span></tt>
except that it generates commas between repetitions, so its second
argument (<tt class="docutils literal"><span class="pre">TINY_print</span></tt>,
here) must have the same signature as <tt class="docutils literal"><span
class="pre">TINY_size</span></tt>. In this case, <tt class="docutils literal"><span
class="pre">TINY_print</span></tt> ignores its repetition
index <tt class="docutils literal"><span class="pre">n</span></tt>,
and simply yields its third argument, <tt class="docutils literal"><span
class="pre">none</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_SUB</span></tt>
implements token subtraction. It's crucial to understand that
although the preprocessor <em>itself</em> can evaluate ordinary
arithmetic expressions:</p>
<pre class="literal-block">#define X 3
...
#if <strong>X - 1 > 0</strong> // OK
<em>whatever</em>
#endif
</pre>
<p>preprocessor <em>metaprograms</em> can only operate on tokens.
Normally, when a macro in the Preprocessor library expects a
numeric argument, it must be passed as a single token. If we had
written <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE-n</span></tt>
instead of <tt class="docutils literal"><span class="pre">BOOST_PP_SUB(TINY_MAX_SIZE,n)</span></tt>
above, the first argument to <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>
would have contained three tokens at each invocation: first <tt class="docutils literal"><span
class="pre">3-0</span></tt>, then <tt class="docutils literal"><span
class="pre">3-1</span></tt>, and finally <tt class="docutils literal"><span
class="pre">3-2</span></tt>. <tt class="docutils literal"><span
class="pre">BOOST_PP_SUB</span></tt>, though, generates
single-token results: first <tt class="docutils literal"><span class="pre">3</span></tt>,
then <tt class="docutils literal"><span class="pre">2</span></tt>,
and finally <tt class="docutils literal"><span class="pre">1</span></tt>,
in successive repetitions.</p>
<div class="sidebar">
<p class="first sidebar-title">Naming Conventions</p>
<p class="last">Note that <tt class="docutils literal"><span class="pre">TINY_print</span></tt>
and <tt class="docutils literal"><span class="pre">TINY_size</span></tt>
are <tt class="docutils literal"><span class="pre">#undef</span></tt>'d
immediately
after they're used, with no intervening <tt class="docutils literal"><span
class="pre">#include</span></tt>s. They can therefore be
thought of as "local" macro definitions. Because the
preprocessor doesn't respect scope boundaries, it's important to
choose names carefully to prevent clashes. We recommend <tt class="docutils literal"><span
class="pre">PREFIXED_lower_case</span></tt> names for local
macros and <tt class="docutils literal"><span class="pre">PREFIXED_UPPER_CASE</span></tt>
names for global ones. The only exceptions are one-letter
lowercase names, which are safe to use for local macros: No
other header is likely to <tt class="docutils literal"><span class="pre">#define</span></tt>
a global single-letter lowercase macro—that would be <em>very</em>
bad manners.</p>
</div>
</div>
<div class="section" id="vertical-repetition">
<h3><a name="vertical-repetition">A.4.1.2 Vertical Repetition</a></h3>
<p>If you send the previous example through your preprocessor,
you'll see one long line containing something like this:</p>
<pre class="literal-block">template <> struct tiny_size< none , none , none > : mpl::int_<0>
{}; template < class T0> struct tiny_size< T0 , none , none > :
mpl::int_<1> {}; template < class T0 , class T1> struct tiny_size
< T0 , T1 , none > : mpl::int_<2> {};
</pre>
<p>The distinguishing feature of horizontal repetition is that all
instances of the repeated pattern are generated on the same line
of preprocessed output. For some jobs, like generating the primary
<tt class="docutils literal"><span class="pre">tiny_size</span></tt>
template, that's perfectly appropriate. In this case, however,
there are at least two disadvantages.</p>
<ol class="arabic simple">
<li>It's hard to verify that our metaprogram is doing the right
thing without reformatting the resulting code by hand.</li>
<li>The efficiency of nested horizontal repetitions varies widely
across preprocessors. Each specialization generated by means of
horizontal repetition contains three other horizontal
repetitions: two invocations of <tt class="docutils literal"><span
class="pre">BOOST_PP_ENUM_PARAMS</span></tt> and one
invocation of <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>.
When <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
is <tt class="docutils literal"><span class="pre">3</span></tt>,
you'll probably never care, but on at least one preprocessor
still in use today, compilation begins to slow noticeably when <tt
class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
reaches <tt class="docutils literal"><span class="pre">8</span></tt>.<a
class="footnote-reference" href="#nest" id="id9" name="id9">[7]</a></li>
</ol>
<blockquote>
<table class="docutils footnote" frame="void" id="nest" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id9" name="nest">[7]</a></td>
<td>That said, other preprocessors can handle 256 * 256
nested repetitions without any speed problems whatsoever.</td>
</tr>
</tbody>
</table>
</blockquote>
<p>The solution to these problems, naturally, is <strong>vertical
repetition</strong>, which generates instances of a pattern
across multiple lines. The Preprocessor library provides two means
of vertical repetition: <strong>local iteration</strong> and <strong>file
iteration</strong>.</p>
<div class="section" id="local-iteration">
<h4><a name="local-iteration">Local Iteration</a></h4>
<p>The most expedient way to demonstrate local iteration in our
example is to replace the invocation of <tt class="docutils literal"><span
class="pre">BOOST_PP_REPEAT</span></tt> with the following:</p>
<pre class="literal-block">#include <boost/preprocessor/<strong>iteration/local.hpp</strong>>
#define BOOST_PP_LOCAL_MACRO(n) TINY_size(~, n, ~)
#define BOOST_PP_LOCAL_LIMITS (0, <strong>TINY_MAX_SIZE - 1</strong>)
<strong>#include</strong> BOOST_PP_LOCAL_ITERATE()
</pre>
<p>Local iteration repeatedly invokes the user-defined macro with
the special name <tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_MACRO</span></tt>,
whose argument will be an iteration index. Since we already had
<tt class="docutils literal"><span class="pre">TINY_size</span></tt>
lying around, we've just defined <tt class="docutils literal"><span
class="pre">BOOST_PP_LOCAL_MACRO</span></tt> to invoke it.
The range of iteration indices are given by another user-defined
macro, <tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_LIMITS</span></tt>,
which must expand to a parenthesized pair of integer values
representing the <em>inclusive</em> range of index values
passed to <tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_MACRO</span></tt>.
Note that this is one of the rare places where the library
expects a numeric argument that can be an expression consisting
of multiple tokens.</p>
<p>Finally, the repetition is initiated by <tt class="docutils literal"><span
class="pre">#include</span></tt>-ing the result of invoking
<tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_ITERATE</span></tt>,
which will ultimately be a file in the Preprocessor library
itself. You may find it surprising that many preprocessors can
handle repeated file inclusion more quickly than nested
horizontal repetition, but that is in fact the case.</p>
<p>If we throw the new example at our preprocessor, we'll see the
following, on three separate lines in the output:</p>
<pre class="literal-block">template <> struct tiny_size< none , none , none > : mpl::int_<0>
{};
template < class T0> struct tiny_size< T0 , none , none > : mpl::
int_<1> {};
template < class T0 , class T1> struct tiny_size< T0 , T1 , none
> : mpl::int_<2> {};
</pre>
<p>That represents a great improvement in verifiability, but it's
still not ideal. As <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
grows, it gets harder and harder to see that the pattern is
generating what we'd like. If we could get some more line breaks
into the output it would retain a more recognizable form.</p>
<p>Both repetition methods we've used so far have another
drawback, though it doesn't show up in this example. Consider
what would happen if <tt class="docutils literal"><span class="pre">tiny_size</span></tt>
had a member function that we wanted to debug. If you've ever
tried to use a debugger to step through a function generated by
a preprocessor macro, you know that it's a frustrating
experience at best: The debugger shows you the line from which
the macro was ultimately invoked, which usually looks nothing at
all like the code that was generated. Worse, as far as the
debugger is concerned, <em>every</em> statement in that
generated function occupies that same line.</p>
</div>
<div class="section" id="file-iteration">
<h4><a name="file-iteration">File Iteration</a></h4>
<p>Clearly, debuggability depends on preserving the association
between generated code and the lines in the source file that
describe the code pattern. File iteration generates pattern
instances by repeatedly <tt class="docutils literal"><span class="pre">#include</span></tt>-ing
the same source file. The effect of file iteration on
debuggability is similar to that of templates: Although separate
instances appear to occupy the same source lines in the
debugger, we do have the experience of stepping through the
function's source code.</p>
<p>To apply file iteration in our example, we can replace our
earlier local iteration code and the definition of <tt class="docutils literal"><span
class="pre">TINY_size</span></tt>, with:</p>
<pre class="literal-block">#include <boost/preprocessor/iteration/iterate.hpp>
#define BOOST_PP_ITERATION_LIMITS (0, TINY_MAX_SIZE - 1)
#define BOOST_PP_FILENAME_1 "tiny_size_spec.hpp"
#include BOOST_PP_ITERATE()
</pre>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_ITERATION_LIMITS</span></tt>
follows the same pattern as <tt class="docutils literal"><span
class="pre">BOOST_PP_LOCAL_LIMITS</span></tt> did, allowing
us to specify an inclusive range of iteration indices. <tt class="docutils literal"><span
class="pre">BOOST_PP_FILENAME_1</span></tt> specifies the
name of the file to repeatedly <tt class="docutils literal"><span
class="pre">#include</span></tt> (we'll show you that file
in a moment). The trailing <tt class="docutils literal"><span class="pre">1</span></tt>
indicates that this is the first nesting level of file
iteration—should we need to invoke file iteration again from
within <tt class="docutils literal"><span class="pre">tiny_size_spec.hpp</span></tt>,
we'd need to use <tt class="docutils literal"><span class="pre">BOOST_PP_FILENAME_2</span></tt>
instead.</p>
<p>The contents of <tt class="docutils literal"><span class="pre">tiny_size_spec.hpp</span></tt>
should look familiar to you; most of it is the same as <tt class="docutils literal"><span
class="pre">TINY_size</span></tt>'s <em>replacement-list</em>,
without the backslashes:</p>
<pre class="literal-block">#define n BOOST_PP_ITERATION()
template <BOOST_PP_ENUM_PARAMS(n, class T)>
struct tiny_size<
BOOST_PP_ENUM_PARAMS(n,T)
BOOST_PP_COMMA_IF(n)
BOOST_PP_ENUM(BOOST_PP_SUB(TINY_MAX_SIZE,n), TINY_print, none)
>
: mpl::int_<n> {};
#undef n
</pre>
<p>The Library transmits the iteration index to us in the result
of <tt class="docutils literal"><span class="pre">BOOST_PP_ITERATION()</span></tt>;
<tt class="docutils literal"><span class="pre">n</span></tt> is
nothing more than a convenient local macro used to reduce
syntactic noise. Note that we didn't use <tt class="docutils literal"><span
class="pre">#include</span></tt> guards because we need <tt
class="docutils literal"><span class="pre">tiny_size_spec.hpp</span></tt>
to be processed multiple times.</p>
<p>The preprocessed result should now preserve the line structure
of the pattern and be more verifiable for larger values of <tt
class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>.
For instance, when <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
is <tt class="docutils literal"><span class="pre">8</span></tt>,
the following excerpt appears in the output of GCC's
preprocessing phase:</p>
<pre class="literal-block"><em>...</em>
template < class T0 , class T1 , class T2 , class T3>
struct tiny_size<
T0 , T1 , T2 , T3
,
none , none , none , none
>
: mpl::int_<4> {};
template < class T0 , class T1 , class T2 , class T3 , class T4>
struct tiny_size<
T0 , T1 , T2 , T3 , T4
,
none , none , none
>
: mpl::int_<5> {};
<em>...etc.</em>
</pre>
</div>
<div class="section" id="self-iteration">
<h4><a name="self-iteration">Self-Iteration</a></h4>
<p>Creating an entirely new file like <tt class="docutils literal"><span
class="pre">tiny_size_spec.hpp</span></tt> each time we want
to express a trivial code pattern for file repetition can be
inconvenient. Fortunately, the library provides a macro that
allows us to place the pattern right in the file that invokes
the iteration. <tt class="docutils literal"><span class="pre">BOOST_PP_IS_ITERATING</span></tt>
is defined to a nonzero value whenever we're inside an
iteration. We can use that value to select between the part of a
file that invokes the iteration and the part that provides the
repeated pattern. Here's a complete <tt class="docutils literal"><span
class="pre">tiny_size.hpp</span></tt> file that demonstrates
self-iteration. Note in particular the placement and use of the
<tt class="docutils literal"><span class="pre">#include</span></tt>
guard <tt class="docutils literal"><span class="pre">TINY_SIZE_HPP_INCLUDED</span></tt>:</p>
<pre class="literal-block">#ifndef <strong>BOOST_PP_IS_ITERATING</strong>
# ifndef TINY_SIZE_HPP_INCLUDED
# define TINY_SIZE_HPP_INCLUDED
# include <boost/preprocessor/repetition.hpp>
# include <boost/preprocessor/arithmetic/sub.hpp>
# include <boost/preprocessor/punctuation/comma_if.hpp>
# include <boost/preprocessor/iteration/iterate.hpp>
# ifndef TINY_MAX_SIZE
# define TINY_MAX_SIZE 3 // default maximum size is 3
# endif
// primary template
template <BOOST_PP_ENUM_PARAMS(TINY_MAX_SIZE, class T)>
struct tiny_size
: mpl::int_<TINY_MAX_SIZE>
{};
// generate specializations
# define BOOST_PP_ITERATION_LIMITS (0, TINY_MAX_SIZE - 1)
# define BOOST_PP_FILENAME_1 "tiny_size.hpp" // this file
# include BOOST_PP_ITERATE()
# endif // TINY_SIZE_HPP_INCLUDED
#else // <strong>BOOST_PP_IS_ITERATING</strong>
# define n BOOST_PP_ITERATION()
# define TINY_print(z, n, data) data
// specialization pattern
template <BOOST_PP_ENUM_PARAMS(n, class T)>
struct tiny_size<
BOOST_PP_ENUM_PARAMS(n,T)
BOOST_PP_COMMA_IF(n)
BOOST_PP_ENUM(BOOST_PP_SUB(TINY_MAX_SIZE,n), TINY_print, none)
>
: mpl::int_<n> {};
# undef TINY_print
# undef n
#endif // <strong>BOOST_PP_IS_ITERATING</strong>
</pre>
</div>
<div class="section" id="more">
<h4><a name="more">More</a></h4>
<p>There's a good deal more to file iteration than what we've been
able to show you here. For more details, we encourage you to
delve into the library's electronic documentation of <tt class="docutils literal"><span
class="pre">BOOST_PP_ITERATE</span></tt> and friends. Also,
it's important to note that no single technique for repetition
is superior to any other: Your choice may depend on convenience,
verifiability, debuggability, compilation speed, and your own
sense of "logical coherence."</p>
</div>
</div>
</div>
<div class="section" id="arithmetic-logical-and-comparison-operations">
<h2><a name="arithmetic-logical-and-comparison-operations">A.4.2 Arithmetic,
Logical, and Comparison Operations</a></h2>
<p>As we mentioned earlier, many of the Preprocessor library
interfaces require single-token numeric arguments, and when those
numbers need to be computed arithmetically, straightforward
arithmetic expressions are inappropriate. We used <tt class="docutils literal"><span
class="pre">BOOST_PP_SUB</span></tt> to subtract two numeric
tokens in our <tt class="docutils literal"><span class="pre">tiny_size</span></tt>
examples. The library contains a suite of operations for
non-negative integral token arithmetic in its <tt class="docutils literal"><span
class="pre">arithmetic/</span></tt> subdirectory, as shown in
Table A.1</p>
<table border="1" class="docutils">
<caption>Preprocessor Library Arithmetic Operations</caption> <colgroup>
<col width="44%" /> <col width="56%" /> </colgroup>
<thead valign="bottom">
<tr>
<th>Expression</th>
<th>Value of Single Token Result</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ADD(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">+</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_DEC(x)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">-</span> <span class="pre">1</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_DIV(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">/</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_INC(x)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">+</span> <span class="pre">1</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_MOD(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">%</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_MUL(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">*</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SUB(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">-</span> <span class="pre">y</span></tt></td>
</tr>
</tbody>
</table>
<p>The <tt class="docutils literal"><span class="pre">logical/</span></tt>
subdirectory contains the convenient Boolean token operations shown
in Table A.2 and the more efficient operations shown in Table A.3,
which require that their operands are either <tt class="docutils literal"><span
class="pre">0</span></tt> or <tt class="docutils literal"><span
class="pre">1</span></tt> (a single bit).</p>
<table border="1" class="docutils">
<caption>Preprocessor Library Integer Logical Operations</caption> <colgroup>
<col width="44%" /> <col width="56%" /> </colgroup>
<thead valign="bottom">
<tr>
<th>Expression</th>
<th>Value of Single Token Result</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_AND(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">&&</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_NOR(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(x</span> <span
class="pre">||</span> <span class="pre">y)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_OR(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">||</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_XOR(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(bool)x</span>
<span class="pre">!=</span> <span class="pre">(bool)y</span>
<span class="pre">?</span> <span class="pre">1</span> <span
class="pre">:</span> <span class="pre">0</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_NOT(x)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">?</span> <span class="pre">0</span> <span class="pre">:</span>
<span class="pre">1</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_BOOL(x)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
<span class="pre">0</span></tt></td>
</tr>
</tbody>
</table>
<table border="1" class="docutils">
<caption>Preprocessor Library Bit Logical Operations</caption> <colgroup>
<col width="44%" /> <col width="56%" /> </colgroup>
<thead valign="bottom">
<tr>
<th>Expression</th>
<th>Value of Single Token Result</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_BITAND(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">&&</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_BITNOR(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">!(x</span> <span
class="pre">||</span> <span class="pre">y)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_BITOR(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">||</span> <span class="pre">y</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_BITXOR(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(bool)x</span>
<span class="pre">!=</span> <span class="pre">(bool)y</span>
<span class="pre">?</span> <span class="pre">1</span> <span
class="pre">:</span> <span class="pre">0</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_COMPL(x)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">?</span> <span class="pre">0</span> <span class="pre">:</span>
<span class="pre">1</span></tt></td>
</tr>
</tbody>
</table>
<p>Finally, the <tt class="docutils literal"><span class="pre">comparison/</span></tt>
subdirectory provides the token integral comparison operations shown
in Table A.4.</p>
<table border="1" class="docutils">
<caption>Preprocessor Library Comparison Operations</caption> <colgroup>
<col width="46%" /> <col width="54%" /> </colgroup>
<thead valign="bottom">
<tr>
<th>Expression</th>
<th>Value of Single Token Result</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_EQUAL(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">==</span> <span class="pre">y</span> <span
class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
<span class="pre">0</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_NOT_EQUAL(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">!=</span> <span class="pre">y</span> <span
class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
<span class="pre">0</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_LESS(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre"><</span> <span class="pre">y</span> <span
class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
<span class="pre">0</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_LESS_EQUAL(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre"><=</span> <span class="pre">y</span> <span
class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
<span class="pre">0</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_GREATER(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">></span> <span class="pre">y</span> <span
class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
<span class="pre">0</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_GREATER_EQUAL(x,y)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">x</span> <span
class="pre">>=</span> <span class="pre">y</span> <span
class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
<span class="pre">0</span></tt></td>
</tr>
</tbody>
</table>
<p>Because it's common to have a choice among several workable
comparison operators, it may be useful to know that <tt class="docutils literal"><span
class="pre">BOOST_PP_EQUAL</span></tt> and <tt class="docutils literal"><span
class="pre">BOOST_PP_NOT_EQUAL</span></tt> are likely to be O(1)
while the other comparison operators are generally slower.</p>
</div>
<div class="section" id="control-structures">
<h2><a name="control-structures">A.4.3 Control Structures</a></h2>
<p>In its <tt class="docutils literal"><span class="pre">control/</span></tt>
directory, the Preprocessor Library supplies a macro <tt class="docutils literal"><span
class="pre">BOOST_PP_IF(c,t,f)</span></tt> that fulfills a
similar role to the one filled by <tt class="docutils literal"><span
class="pre">mpl::if_</span></tt>. To explore the "control"
group, we'll generate code for a framework of generic function
objects: the Boost Function Library.<a class="footnote-reference" href="#function"
id="id10" name="id10">[8]</a> <tt class="docutils literal"><span
class="pre">boost::function</span></tt> is partially specialized
to match function type arguments of each arity up to the maximum
supported by the library:</p>
<pre class="literal-block">template <class Signature> struct function; // primary template
template <class R> // arity = 0
struct function<R()>
<em>definition not shown...</em>
template <class R, class A0> // arity = 1
struct function<R(A0)>
<em>definition not shown...</em>
template <class R, class A0, class A1> // arity = 2
struct function<R(A0,A1)>
<em>definition not shown...</em>
template <class R, class A0, class A1, class A2> // arity = 3
struct function<R(A0,A1,A2)>
<em>definition not shown...</em>
<em>etc.</em>
</pre>
<table class="docutils footnote" frame="void" id="function" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id10" name="function">[8]</a></td>
<td>We touched briefly on the design of Boost Function when we
discussed type erasure in Chapter 9. See the Function library
documentation at <tt class="docutils literal"><span class="pre">boost_1_32_0/libs/function/index.html</span></tt>
on the CD that accompanies this book for more information.</td>
</tr>
</tbody>
</table>
<p>We've already covered a few strategies that can be used to generate
the pattern above, so we won't belabor that part of the problem; the
file iteration approach we used for <tt class="docutils literal"><span
class="pre">tiny_size</span></tt> would be fine:</p>
<pre class="literal-block">#ifndef BOOST_PP_IS_ITERATING
# ifndef BOOST_FUNCTION_HPP_INCLUDED
# define BOOST_FUNCTION_HPP_INCLUDED
# include <boost/preprocessor/repetition.hpp>
# include <boost/preprocessor/iteration/iterate.hpp>
# ifndef FUNCTION_MAX_ARITY
# define FUNCTION_MAX_ARITY 15
# endif
<strong>template <class Signature> struct function;</strong> // primary template
// generate specializations
# define BOOST_PP_ITERATION_LIMITS (0, FUNCTION_MAX_ARITY)
# define BOOST_PP_FILENAME_1 "boost/function.hpp" // this file
# include BOOST_PP_ITERATE()
# endif // BOOST_FUNCTION_HPP_INCLUDED
#else // BOOST_PP_IS_ITERATING
# define n BOOST_PP_ITERATION()
// specialization pattern
<strong>template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)></strong>
<strong>struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )></strong>
<em>definition not shown...</em>
# undef n
#endif // BOOST_PP_IS_ITERATING
</pre>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_TRAILING_PARAMS</span></tt>,
used above, is just like <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>
except that when its first argument is not <tt class="docutils literal"><span
class="pre">0</span></tt>, it generates a leading comma.</p>
<div class="section" id="argument-selection">
<h3><a name="argument-selection">A.4.3.1 Argument Selection</a></h3>
<p>For the sake of interoperability with C++ standard library
algorithms, it might be nice if <tt class="docutils literal"><span
class="pre">function</span></tt>s of one or two arguments were
derived from appropriate specializations of <tt class="docutils literal"><span
class="pre">std::unary_function</span></tt> or <tt class="docutils literal"><span
class="pre">std::binary_function</span></tt>, respectively.<a
class="footnote-reference" href="#ebo" id="id11" name="id11">[9]</a>
<tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
is a great tool for dealing with special cases:</p>
<pre class="literal-block"># include <boost/preprocessor/control/if.hpp>
# include <boost/preprocessor/comparison/equal.hpp>
// specialization pattern
template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
BOOST_PP_IF(
BOOST_PP_EQUAL(n,2), <strong>: std::binary_function<A0, A1, R></strong>
, BOOST_PP_IF(
BOOST_PP_EQUAL(n,1), <strong>: std::unary_function<A0, R></strong>
, <em>...empty argument...</em>
)
)
{ <em>...class body omitted...</em> };
</pre>
<table class="docutils footnote" frame="void" id="ebo" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr>
<td class="label"><a class="fn-backref" href="#id11" name="ebo">[9]</a></td>
<td>While derivation from <tt class="docutils literal"><span
class="pre">std::unary_function</span></tt> or <tt class="docutils literal"><span
class="pre">std::binary_function</span></tt> might be
necessary for interoperability with some older library
implementations, it may inhibit the Empty Base Optimization
(EBO) from taking effect when two such derived classes are
part of the same object. For more information, see section
9.4. In general, it's better to expose <tt class="docutils literal"><span
class="pre">first_argument_type</span></tt>, <tt class="docutils literal"><span
class="pre">second_argument_type</span></tt>, and <tt class="docutils literal"><span
class="pre">result_type</span></tt> <tt class="docutils literal"><span
class="pre">typedef</span></tt>s directly.</td>
</tr>
</tbody>
</table>
<p>Well, our first attempt has run into several problems. First off,
you're not allowed to pass an empty argument to the preprocessor.<a
class="footnote-reference" href="#c99" id="id12" name="id12">[3]</a>
Secondly, because angle brackets don't get special treatment, the
commas in the <tt class="docutils literal"><span class="pre">std::unary_function</span></tt>
and <tt class="docutils literal"><span class="pre">std::binary_function</span></tt>
specializations above are treated as macro argument separators,
and the preprocessor will complain that we've passed the wrong
number of arguments to <tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
in two places.</p>
<p>Because it captures all of the issues, let's focus on the inner <tt
class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
invocation for a moment. The strategy that <tt class="docutils literal"><span
class="pre">mpl::eval_if</span></tt> uses, of selecting a
nullary function to invoke, could work nicely here. The
preprocessor doesn't have a direct analogue for <tt class="docutils literal"><span
class="pre">mpl::eval_if</span></tt>, but it doesn't really
need one: We can get the right effect by adding a second set of
parentheses to <tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>.</p>
<pre class="literal-block">#define BOOST_FUNCTION_unary() : std::unary_function<A0,R>
#define BOOST_FUNCTION_empty() // nothing
...
, BOOST_PP_IF(
BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary
, BOOST_FUNCTION_empty
)<strong>()</strong>
#undef BOOST_FUNCTION_empty
#undef BOOST_FUNCTION_unary
</pre>
<p>A nullary macro that generates nothing is so commonly needed that
the library's "facilities" group provides one: <tt class="docutils literal"><span
class="pre">BOOST_PP_EMPTY</span></tt>. To complete the
example we'll need to delay evaluation all the way to the outer <tt
class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
invocation, because <tt class="docutils literal"><span class="pre">std::binary_function<A0,A1,R></span></tt>
also has a "comma problem":</p>
<pre class="literal-block"># include <boost/preprocessor/<strong>facilities/empty.hpp</strong>>
# define BOOST_FUNCTION_binary() : std::binary_function<A0,A1,R>
# define BOOST_FUNCTION_unary() : std::unary_function<A0,R>
// specialization pattern
template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
BOOST_PP_IF(
BOOST_PP_EQUAL(n,2), BOOST_FUNCTION_binary
, BOOST_PP_IF(
BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary
, <strong>BOOST_PP_EMPTY</strong>
)
)<strong>()</strong>
{
<em>...class body omitted...</em>
};
# undef BOOST_FUNCTION_unary
# undef BOOST_FUNCTION_binary
# undef n
</pre>
<p>Note that because we happened to be using file iteration, we
could have also used <tt class="docutils literal"><span class="pre">#if</span></tt>
on <tt class="docutils literal"><span class="pre">n</span></tt>'s
value directly:</p>
<pre class="literal-block"> template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
<strong>#if n == 2</strong>
: std::binary_function<A0, A1, R>
<strong>#elif n == 1</strong>
: std::unary_function<A0, R>
<strong>#endif</strong>
</pre>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
has the advantage of enabling us to encapsulate the logic in a
reusable macro, parameterized on <tt class="docutils literal"><span
class="pre">n</span></tt>, that is compatible with all
repetition constructs:</p>
<pre class="literal-block">#define BOOST_FUNCTION_BASE(n) \
BOOST_PP_IF(BOOST_PP_EQUAL(n,2), BOOST_FUNCTION_binary \
, BOOST_PP_IF(BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary \
, BOOST_PP_EMPTY \
) \
)()
</pre>
</div>
<div class="section" id="other-selection-constructs">
<h3><a name="other-selection-constructs">A.4.3.2 Other Selection
Constructs</a></h3>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_IDENTITY</span></tt>,
also in the "facilities" group, is an interesting cousin of <tt class="docutils literal"><span
class="pre">BOOST_PP_EMPTY</span></tt>:</p>
<pre class="literal-block">#define BOOST_PP_IDENTITY(tokens) tokens BOOST_PP_EMPTY
</pre>
<p>You can think of it as creating a nullary macro that returns <tt
class="docutils literal"><span class="pre">tokens</span></tt>:
When empty parentheses are appended, the trailing <tt class="docutils literal"><span
class="pre">BOOST_PP_EMPTY</span></tt> is expanded leaving
just <tt class="docutils literal"><span class="pre">tokens</span></tt>
behind. If we had wanted inheritance from <tt class="docutils literal"><span
class="pre">mpl::empty_base</span></tt> when <tt class="docutils literal"><span
class="pre">function</span></tt>'s arity is not one or two, we
could have used <tt class="docutils literal"><span class="pre">BOOST_PP_IDENTITY</span></tt>:</p>
<pre class="literal-block">// specialization pattern
template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
BOOST_PP_IF(
BOOST_PP_EQUAL(n,2), BOOST_FUNCTION_binary
, BOOST_PP_IF(
BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary
, <strong>BOOST_PP_IDENTITY(: mpl::empty_base)</strong>
)
)<strong>()</strong>
{
<em>...class body omitted...</em>
};
</pre>
<p>It's also worth knowing about <tt class="docutils literal"><span
class="pre">BOOST_PP_EXPR_IF</span></tt>, which generates its
second argument or nothing, depending on the Boolean value of its
first:</p>
<pre class="literal-block">#define BOOST_PP_EXPR_IF(c,tokens) \
BOOST_PP_IF(c,BOOST_PP_IDENTITY(tokens),BOOST_PP_EMPTY)()
</pre>
<p>So <tt class="docutils literal"><span class="pre">BOOST_PP_EXPR_IF(1,foo)</span></tt>
expands to <tt class="docutils literal"><span class="pre">foo</span></tt>,
while <tt class="docutils literal"><span class="pre">BOOST_PP_EXPR_IF(0,foo)</span></tt>
expands to nothing.</p>
</div>
</div>
<div class="section" id="token-pasting">
<h2><a name="token-pasting">A.4.4 Token Pasting</a></h2>
<p>It would be nice if there were a generic way to access the return
and parameter types of <em>all</em> function objects, rather than
just the unary and binary ones. A metafunction returning the
signature as an MPL sequence would do the trick. We could just
specialize <tt class="docutils literal"><span class="pre">signature</span></tt>
for each <tt class="docutils literal"><span class="pre">function</span></tt>
arity:</p>
<pre class="literal-block">template <class F> struct signature; // primary template
// partial specializations for boost::function
template <class R>
struct signature<function<R()> >
: mpl::vector1<R> {};
template <class R, class A0>
struct signature<function<R(A0)> >
: mpl::vector2<R,A0> {};
template <class R, class A0, class A1>
struct signature<function<R(A0,A1)> >
: mpl::vector3<R,A0,A1> {};
...
</pre>
<p>To generate these specializations, we might add the following to
our pattern:</p>
<pre class="literal-block">template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
struct signature<function<R( BOOST_PP_ENUM_PARAMS(n,A) )> >
: mpl::<strong>BOOST_PP_CAT</strong>(vector,n)<
R BOOST_PP_ENUM_TRAILING_PARAMS(n,A)
> {};
</pre>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_CAT</span></tt>
implements <strong>token pasting</strong>; its two arguments are
"glued" together into a single token. Since this is a
general-purpose macro, it sits in <tt class="docutils literal"><span
class="pre">cat.hpp</span></tt> at the top level of the
library's directory tree.</p>
<p>Although the preprocessor has a built-in token-pasting operator, <tt
class="docutils literal"><span class="pre">##</span></tt>, it only
works within a macro definition. If we'd used it here, it wouldn't
have taken effect at all:</p>
<pre class="literal-block">template <class R>
struct signature<function<R()> >
: mpl::<strong>vector##1</strong><R> {};
template <class R, class A0>
struct signature<function<R(A0)> >
: mpl::<strong>vector##2</strong><R,A0> {};
template <class R, class A0, class A1>
struct signature<function<R(A0,A1)> >
: mpl::<strong>vector##3</strong><R,A0,A1> {};
...
</pre>
<p>Also, <tt class="docutils literal"><span class="pre">##</span></tt>
often yields surprising results by taking effect before its
arguments have been expanded:</p>
<pre class="literal-block">#define N 10
#define VEC(i) vector##i
VEC(N) // vectorN
</pre>
<p>By contrast, <tt class="docutils literal"><span class="pre">BOOST_PP_CAT</span></tt>
delays concatenation until after its arguments have been fully
evaluated:</p>
<pre class="literal-block">#define N 10
#define VEC(i) BOOST_PP_CAT(vector,i)
VEC(N) // vector10
</pre>
</div>
<div class="section" id="data-types">
<h2><a name="data-types">A.4.5 Data Types</a></h2>
<p>The Preprocessor library also provides <strong>data types</strong>,
which you can think of as being analogous to the MPL's type
sequences. Preprocessor data types store <em>macro arguments</em>
instead of C++ types.</p>
<div class="section" id="sequences">
<h3><a name="sequences">A.4.5.1 Sequences</a></h3>
<p>A <strong>sequence</strong> (or <strong>seq</strong> for short)
is any string of nonempty parenthesized <em>macro arguments</em>.
For instance, here's a three-element sequence:</p>
<pre class="literal-block">#define MY_SEQ (f(12))(a + 1)(foo)
</pre>
<p>Here's how we might use a sequence to generate specializations of
the <tt class="docutils literal"><span class="pre">is_integral</span></tt>
template from the Boost Type Traits library (see Chapter 2):</p>
<pre class="literal-block">#include <boost/preprocessor/seq.hpp>
template <class T>
struct is_integral : mpl::false_ {};
// a seq of integral types with unsigned counterparts
#define BOOST_TT_basic_ints (char)(short)(int)(long)
// generate a seq containing "signed t" and "unsigned t"
#define BOOST_TT_int_pair(r,data,t) (signed t)(unsigned t)
// a seq of all the integral types
#define BOOST_TT_ints \
(bool)(char) \
BOOST_PP_SEQ_FOR_EACH(BOOST_TT_int_pair, ~, BOOST_TT_basic_ints)
// generate an is_integral specialization for type t
#define BOOST_TT_is_integral_spec(r,data,t) \
template <> \
struct is_integral<t> : mpl::true_ {};
BOOST_PP_SEQ_FOR_EACH(BOOST_TT_is_integral_spec, ~, BOOST_TT_ints)
#undef BOOST_TT_is_integral_spec
#undef BOOST_TT_ints
#undef BOOST_TT_int_pair
#undef BOOST_TT_basic_ints
</pre>
<p><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH</span></tt>
is a higher-order macro, similar to <tt class="docutils literal"><span
class="pre">BOOST_PP_REPEAT</span></tt>, that invokes its
first argument on each element of its third argument.</p>
<p>Sequences are the most efficient, most flexible, and
easiest-to-use of the library's data structures, provided that you
never need to make an empty one: An empty sequence would contain
no tokens, and so couldn't be passed as a macro argument. The
other data structures covered here all have an empty
representation.</p>
<p>The facilities for manipulating sequences are all in the
library's <tt class="docutils literal"><span class="pre">seq/</span></tt>
subdirectory. They are summarized in Table A.5, where <tt class="docutils literal"><span
class="pre">t</span></tt> is the sequence <tt class="docutils literal"><span
class="pre">(</span></tt><em>t</em><sub>0</sub><tt class="docutils literal"><span
class="pre">)(</span></tt><em>t</em><sub>1</sub><tt class="docutils literal"><span
class="pre">)...(</span></tt><em>t</em><sub>k</sub><tt class="docutils literal"><span
class="pre">)</span></tt>. Where <em>s</em>, <em>r</em>, and
<em>d</em> appear, they have a similar purpose to the <tt class="docutils literal"><span
class="pre">z</span></tt> parameters we discussed earlier (and
suggested you ignore for now).</p>
<table border="1" class="docutils">
<caption>Preprocessor Sequence Operations</caption> <colgroup> <col
width="51%" /> <col width="49%" /> </colgroup>
<thead valign="bottom">
<tr>
<th>Expression</th>
<th>Result</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_CAT(t)</span></tt></td>
<td><em>t</em><sub>0</sub><em>t</em><sub>1</sub>...<em>t</em><sub>k</sub></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_ELEM(n,t)</span></tt></td>
<td><em>t</em><sub>n</sub></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_ENUM(t)</span></tt></td>
<td><em>t</em><sub>0</sub>, <em>t</em><sub>1</sub>, ...<em>t</em><sub>k</sub></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FILTER(pred,data,t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">t</span></tt>
without the elements that don't satisfy <tt class="docutils literal"><span
class="pre">pred</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FIRST_N(n,t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>n-1</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOLD_LEFT(op,</span>
<span class="pre">x,</span> <span class="pre">t)</span></tt></td>
<td>...<tt class="docutils literal"><span class="pre">op(</span></tt><em>s</em><tt
class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
class="docutils literal"><span class="pre">,x</span></tt>,<em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">),</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">),</span></tt><em>t</em><sub>2</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...</td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOLD_RIGHT(op,</span>
<span class="pre">x,</span> <span class="pre">t)</span></tt></td>
<td>...<tt class="docutils literal"><span class="pre">op(</span></tt><em>s</em><tt
class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
class="docutils literal"><span class="pre">,x</span></tt>,<em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">),</span></tt><em>t</em><sub>k-1</sub><tt
class="docutils literal"><span class="pre">),</span></tt>
<em>t</em><sub>k-2</sub><tt class="docutils literal"><span class="pre">)</span></tt>...</td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH(f,</span>
<span class="pre">x,</span> <span class="pre">t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">f(</span></tt><em>r</em><tt
class="docutils literal"><span class="pre">,</span> <span
class="pre">x,</span></tt><em>t</em><sub>0</sub><tt class="docutils literal"><span
class="pre">)</span> <span class="pre">f(</span></tt><em>r</em><tt
class="docutils literal"><span class="pre">,</span> <span
class="pre">x,</span></tt><em>t</em><sub>1</sub><tt class="docutils literal"><span
class="pre">)</span></tt>...<tt class="docutils literal"><span
class="pre">f(</span></tt><em>r</em><tt class="docutils literal"><span
class="pre">,</span> <span class="pre">x,</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH_I(g,</span>
<span class="pre">x,</span> <span class="pre">t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">g(</span></tt><em>r</em><tt
class="docutils literal"><span class="pre">,</span> <span
class="pre">x,</span> <span class="pre">0,</span></tt>
<em>t</em><sub>0</sub><tt class="docutils literal"><span class="pre">)</span>
<span class="pre">g(</span></tt><em>r</em><tt class="docutils literal"><span
class="pre">,</span> <span class="pre">x,</span> <span
class="pre">1,</span></tt> <em>t</em><sub>1</sub><tt class="docutils literal"><span
class="pre">)</span></tt>... <tt class="docutils literal"><span
class="pre">g(</span></tt><em>r</em><tt class="docutils literal"><span
class="pre">,</span> <span class="pre">x,</span> <span
class="pre">k,</span></tt> <em>t</em><sub>k</sub><tt class="docutils literal"><span
class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH_PRODUCT(h,</span>
<span class="pre">x,</span> <span class="pre">t)</span></tt></td>
<td>
<dl class="first last docutils">
<dt>Cartesian product—</dt>
<dd>see online docs</dd>
</dl>
</td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_INSERT(t,i,tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i-1</sub><tt
class="docutils literal"><span class="pre">)(tokens)</span>
<span class="pre">(</span></tt><em>t</em><sub>i</sub><tt class="docutils literal"><span
class="pre">)(</span></tt><em>t</em><sub>i+1</sub><tt class="docutils literal"><span
class="pre">)</span></tt>...<tt class="docutils literal"><span
class="pre">(</span></tt><em>t</em><sub>k</sub><tt class="docutils literal"><span
class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_POP_BACK(t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k-1</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_POP_FRONT(t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>2</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_PUSH_BACK(t,tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)(tokens)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_PUSH_FRONT(t,tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(tokens)(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REMOVE(t,i)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i-1</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>i+1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REPLACE(t,i,tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i-1</sub><tt
class="docutils literal"><span class="pre">)(tokens)(</span></tt><em>t</em><sub>i+1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REST_N(n,t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>n</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>n+1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REVERSE(t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>k-1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_HEAD(t)</span></tt></td>
<td><em>t</em><sub>0</sub></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TAIL(t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>2</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_SIZE(t)</span></tt></td>
<td><em>k+1</em></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_SUBSEQ(t,i,m)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i</sub><tt
class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>i+1</sub><tt
class="docutils literal"><span class="pre">)</span></tt>...<tt
class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i+m-1</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TO_ARRAY(t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em>
<tt class="docutils literal"><span class="pre">,(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...<em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TO_TUPLE(t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt> <em>t</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...<em>t</em><sub>k</sub><tt
class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TRANSFORM(f,</span>
<span class="pre">x,</span> <span class="pre">t)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(f(</span></tt><em>r</em><tt
class="docutils literal"><span class="pre">,x,</span></tt><em>t</em><sub>0</sub><tt
class="docutils literal"><span class="pre">))</span> <span
class="pre">(f(</span></tt><em>r</em><tt class="docutils literal"><span
class="pre">,x,</span></tt><em>t</em><sub>1</sub><tt class="docutils literal"><span
class="pre">))</span></tt>...<tt class="docutils literal"><span
class="pre">(f(</span></tt><em>r</em><tt class="docutils literal"><span
class="pre">,x,</span></tt><em>t</em><sub>k</sub><tt class="docutils literal"><span
class="pre">))</span></tt></td>
</tr>
</tbody>
</table>
<p>It's worth noting that while there is no upper limit on the
length of a sequence, operations such as <tt class="docutils literal"><span
class="pre">BOOST_PP_SEQ_ELEM</span></tt> that take numeric
arguments will only work with values up to 256.</p>
</div>
<div class="section" id="tuples">
<h3><a name="tuples">A.4.5.2 Tuples</a></h3>
<p>A <strong>tuple</strong> is a very simple data structure for
which the library provides random access and a few other basic
operations. A tuple takes the form of a parenthesized,
comma-separated list of <em>macro arguments</em>. For example,
this is a three-element tuple:</p>
<pre class="literal-block">#define TUPLE3 (f(12), a + 1, foo)
</pre>
<p>The operations in the library's <tt class="docutils literal"><span
class="pre">tuple/</span></tt> subdirectory can handle tuples
of up to 25 elements. For example, a tuple's <tt class="docutils literal"><span
class="pre">N</span></tt>th element can be accessed via <tt class="docutils literal"><span
class="pre">BOOST_PP_TUPLE_ELEM</span></tt>, as follows:</p>
<pre class="literal-block"> // length index tuple
BOOST_PP_TUPLE_ELEM( 3 , 1 , TUPLE3) // a + 1
</pre>
<p>Notice that we had to pass the tuple's length as the second
argument to <tt class="docutils literal"><span class="pre">BOOST_PP_TUPLE_ELEM</span></tt>;
in fact, <em>all</em> tuple operations require explicit
specification of the tuple's length. We're not going to summarize
the other four operations in the "tuple" group here—you can
consult the Preprocessor library's electronic documentation for
more details. We note, however, that sequences can be transformed
into tuples with <tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TO_TUPLE</span></tt>,
and nonempty tuples can be transformed back into sequences with <tt
class="docutils literal"><span class="pre">BOOST_PP_TUPLE_TO_SEQ</span></tt>.</p>
<p>The greatest strength of tuples is that they conveniently take
the same representation as a macro argument list:</p>
<pre class="literal-block">#define FIRST_OF_THREE(a1,a2,a3) a1
#define SECOND_OF_THREE(a1,a2,a3) a2
#define THIRD_OF_THREE(a1,a2,a3) a3
// uses tuple as an argument list
# define SELECT(selector, tuple) <strong>selector tuple</strong>
SELECT(THIRD_OF_THREE, TUPLE3) // foo
</pre>
</div>
<div class="section" id="arrays">
<h3><a name="arrays">A.4.5.3 Arrays</a></h3>
<p>An <strong>array</strong> is just a tuple containing a
non-negative integer and a tuple of that length:</p>
<pre class="literal-block">#define ARRAY3 ( 3, TUPLE3 )
</pre>
<p>Because an array carries its length around with it, the library's
interface for operating on arrays is much more convenient than the
one used for tuples:</p>
<pre class="literal-block">BOOST_PP_ARRAY_ELEM(1, ARRAY3) // a + 1
</pre>
<p>The facilities for manipulating arrays of up to 25 elements are
all in the library's <tt class="docutils literal"><span class="pre">array/</span></tt>
subdirectory. They are summarized in Table A.6, where <tt class="docutils literal"><span
class="pre">a</span></tt> is the array <tt class="docutils literal"><span
class="pre">(</span></tt><em>k</em><tt class="docutils literal"><span
class="pre">,</span> <span class="pre">(</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,...</span></tt><em>a</em><sub>k-1</sub><tt
class="docutils literal"><span class="pre">))</span></tt>.</p>
<table border="1" class="docutils">
<caption>Preprocessor Array Operations</caption> <colgroup> <col
width="52%" /> <col width="48%" /> </colgroup>
<thead valign="bottom">
<tr>
<th>Expression</th>
<th>Result</th>
</tr>
</thead>
<tbody valign="top">
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_DATA(a)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">)</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_ELEM(i,a)</span></tt></td>
<td><em>a</em><sub>i</sub></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_INSERT(a,</span>
<span class="pre">i,</span> <span class="pre">tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em><tt
class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...<em>a</em><sub>i-1</sub><tt
class="docutils literal"><span class="pre">,</span> <span
class="pre">tokens,</span></tt> <em>a</em><sub>i</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>i+1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_POP_BACK(a)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k-1</em><tt
class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-2</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_POP_FRONT(a)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k-1</em><tt
class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>2</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_PUSH_BACK(a,</span>
<span class="pre">tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em><tt
class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">,</span>
<span class="pre">tokens))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_PUSH_FRONT(a,</span>
<span class="pre">tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em><tt
class="docutils literal"><span class="pre">,(tokens,</span></tt>
<em>a</em><sub>1</sub><tt class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>2</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_REMOVE(a,</span>
<span class="pre">i)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k-1</em><tt
class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>i-1</sub><tt class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>i+1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_REPLACE(a,</span>
<span class="pre">i,</span> <span class="pre">tokens)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k</em><tt
class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>i-1</sub><tt class="docutils literal"><span class="pre">,</span>
<span class="pre">tokens,</span></tt> <em>a</em><sub>i+1</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_REVERSE(a)</span></tt></td>
<td><tt class="docutils literal"><span class="pre">(</span></tt><em>k</em><tt
class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>k-1</sub><tt
class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>k-2</sub><tt
class="docutils literal"><span class="pre">,</span></tt>...
<em>a</em><sub>1</sub><tt class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>0</sub><tt
class="docutils literal"><span class="pre">))</span></tt></td>
</tr>
<tr>
<td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_SIZE(a)</span></tt></td>
<td><em>k</em></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="lists">
<h3><a name="lists">A.4.5.4 Lists</a></h3>
<p>A <strong>list</strong> is a two-element tuple whose first
element is the first element of the list, and whose second element
is a list of the remaining elements, or <tt class="docutils literal"><span
class="pre">BOOST_PP_NIL</span></tt> if there are no remaining
elements. Lists have access characteristics similar to those of a
runtime linked list. Here is a three-element list:</p>
<pre class="literal-block">#define LIST3 (<strong>f(12)</strong>, (<strong>a + 1</strong>, (<strong>foo</strong>, BOOST_PP_NIL)))
</pre>
<p>The facilities for manipulating lists are all in the library's <tt
class="docutils literal"><span class="pre">list/</span></tt>
subdirectory. Because the operations are a subset of those
provided for sequences, we're not going to summarize them here—it
should be easy to understand the list operations by reading the
documentation on the basis of our coverage of sequences.</p>
<p>Like sequences, lists have no fixed upper length bound. Unlike
sequences, lists can also be empty. It's rare to need more than 25
elements in a preprocessor data structure, and lists tend to be
slower to manipulate and harder to read than any of the other
structures, so they should normally be used only as a last resort.</p>
</div>
</div>
</div>
<div class="section" id="exercise">
<h1><a name="exercise">A.5 Exercise</a></h1>
<dl class="docutils">
<dt>A-0</dt>
<dd>Fully preprocessor-ize the <tt class="docutils literal"><span class="pre">tiny</span></tt>
type sequence implemented in Chapter 5 so that all boilerplate code
is eliminated and the maximum size of a <tt class="docutils literal"><span
class="pre">tiny</span></tt> sequence can be adjusted by
changing <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>.</dd>
</dl>
</div>
</div>
<hr class="docutils footer" />
<div class="footer"> Generated on: 2005-10-17 19:34 UTC. Generated by <a class="reference"
href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference"
href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
source. </div>
</body>
</html>