| Copyright: | From "C++ Template Metaprogramming," by David Abrahams and Aleksey Gurtovoy. Copyright (c) 2005 by Pearson Education, Inc. Reprinted with permission. |
|---|---|
| ISBN: | 0321227255 |
Even with the full power of template metaprogramming and the Boost Metaprogramming library 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 tiny_size:
template <class T0, class T1, class T2>
struct tiny_size
: mpl::int_<3> {};
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:
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> {};
In this case there is only a small amount of code with such a "mechanical" flavor, but had we been implementing large instead of tiny, 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.
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...
...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 #defines in code or -D options on the compiler's command line, making build integration trivial. For example, we might parameterize the primary tiny_size template above as follows:
#include <boost/preprocessor/repetition/enum_params.hpp>
#ifndef TINY_MAX_SIZE
# define TINY_MAX_SIZE 3 // default maximum size is 3
#endif
template <BOOST_PP_ENUM_PARAMS(TINY_MAX_SIZE, class T)>
struct tiny_size
: mpl::int_<TINY_MAX_SIZE>
{};
To test the metaprogram, run your compiler in its "preprocessing" mode (usually the -E option), with the Boost root directory in your #include path. For instance:[1]
g++ -P -E -Ipath/to/boost_1_32_0 -I. test.cpp
| [1] | GCC's -P option inhibits the generation of source file and line number markers in preprocessed output. |
Given the appropriate metaprograms, users would be able to adjust not only the number of parameters to tiny_size, but the maximum size of the entire tiny implementation just by #define-ing TINY_MAX_SIZE.
The Boost Preprocessor library [MK04] 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 BOOST_PP_ENUM_PARAMS) 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 library works. We will show you enough at a high level that you'll be able to use the library productively and learn the rest on your own.
| [MK04] | Paul Mensonides and Vesa Karvonen. "The Boost Preprocessor Library." http://www.boost.org/libs/preprocessor. |
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.
The fundamental unit of data in the preprocessor is the preprocessing token. 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 preprocessing tokens and regular tokens (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.
Preprocessor macros come in two flavors. Object-like macros can be defined this way:
#define identifier replacement-list
where the identifier names the macro being defined, and replacement-list is a sequence of zero or more tokens. Where the identifier appears in subsequent program text, it is expanded by the preprocessor into its replacement-list.
Function-like macros, which act as the "metafunctions of the preprocessing phase," are defined as follows:
#define identifier(a1, a2, ... an) replacement-list
where each ai is an identifier naming a macro parameter. When the macro name appears in subsequent program text followed by a suitable argument list, it is expanded into its replacement-list, except that each argument is substituted for the corresponding parameter where it appears in the replacement-list.[2]
| [2] | 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. |
Definition
A macro argument is a nonempty sequence of:
This definition has consequences for preprocessor metaprogramming that must not be underestimated. Note, first of all, that the following tokens have special status:
, ( )
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:
#define FOO(X) X // Unary identity macro FOO(,) // un-parenthesized comma or two empty arguments FOO()) // unmatched parenthesis or missing argument
Note also that the following tokens do not have special status; the preprocessor knows nothing about matched pairs of braces, brackets, or angle brackets:
{ } [ ] < >
As a result, these lines are also ill-formed:
FOO(std::pair<int, long>) // two arguments
FOO({ int x = 1, y = 2; return x+y; }) // two arguments
It is possible to pass either string of tokens above as part of a single macro argument, provided it is parenthesized:
FOO((std::pair<int,int>)) // one argument
FOO(({ int x = 1, y = 2; return x+y; })) // one argument
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.[3] 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 and 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.
| [3] | (1, 2) 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. |
Since in-depth coverage of the Boost Preprocessor library is beyond the scope of this book, we'll try to give you the tools 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 libs/preprocessor/ subdirectory of your Boost installation.
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 boost/preprocessor/ 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 #includes all the headers in that subdirectory. For example, boost/preprocessor/selection.hpp does nothing more than to #include the min.hpp and max.hpp headers that comprise the contents of boost/preprocessor/selection/. The headers whose names don't correspond to subdirectories generally declare a macro whose name is the same as the name of the header, without the extension, and with a BOOST_PP_ prefix. For example, boost/preprocessor/selection/max.hpp declares BOOST_PP_MAX.
You'll also notice that often a header will declare an additional macro with a _D, _R, or _Z suffix.[4] For instance, boost/preprocessor/selection/max.hpp also declares BOOST_PP_MAX_D. 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.
| [4] | Macros with _1ST, _2ND, or _3RD suffixes, if they appear, should be ignored for a different reason: They are deprecated and will be removed from the library soon. |
In this section we'll discuss the basic abstractions of the Preprocessor library, and give some simple examples of each.
The repeated generation of class T0, class T1... class Tn that we achieved using BOOST_PP_ENUM_PARAMS was a specific case of the general concept of horizontal repetition. 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 repetition/ subdirectory.
To generate the tiny_size specializations using horizontal repetition, we might write the following:
#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
The code generation process is kicked off by calling BOOST_PP_REPEAT, a higher-order macro that repeatedly invokes the macro named by its second argument (TINY_size). 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, TINY_size doesn't use that data, so the choice to pass ~ was arbitrary.[5]
| [5] | ~ is not an entirely arbitrary choice. Both @ and $ 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 ignored might be subject to macro expansion, leading to unexpected results. |
Each time the TINY_size macro is invoked by BOOST_PP_REPEAT, it generates a different specialization of tiny_size. The macro accepts three parameters.
Because its replacement-list covers several lines, all but the last line of TINY_size is continued with a trailing backslash. The first few of those lines just invoke BOOST_PP_ENUM_PARAMS (which we already used in the primary template) to generate comma-separated lists, so each invocation of TINY_size produces something equivalent to:[6]
template <class T0, class T1, ... class Tn-1>
struct tiny_size<
T0, T1, ... Tn-1
...more...
>
: mpl::int_<n> {};
| [6] | Note that the line continuation characters and the newlines following them are removed by the preprocessor, so the resulting code actually appears on a single line in the preprocessed output. |
BOOST_PP_COMMA_IF generates a comma if its numeric argument is not 0. When n is 0, the list generated by the preceding line will be empty, and a leading comma directly following the < character would be ill-formed.
The next line uses BOOST_PP_ENUM to generate TINY_MAX_SIZE-n comma-separated copies of none. BOOST_PP_ENUM is just like BOOST_PP_REPEAT except that it generates commas between repetitions, so its second argument (TINY_print, here) must have the same signature as TINY_size. In this case, TINY_print ignores its repetition index n, and simply yields its third argument, none.
BOOST_PP_SUB implements token subtraction. It's crucial to understand that although the preprocessor itself can evaluate ordinary arithmetic expressions:
#define X 3 ... #if X - 1 > 0 // OK whatever #endif
preprocessor metaprograms 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 TINY_MAX_SIZE-n instead of BOOST_PP_SUB(TINY_MAX_SIZE,n) above, the first argument to BOOST_PP_ENUM would have contained three tokens at each invocation: first 3-0, then 3-1, and finally 3-2. BOOST_PP_SUB, though, generates single-token results: first 3, then 2, and finally 1, in successive repetitions.
If you send the previous example through your preprocessor, you'll see one long line containing something like this:
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> {};
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 tiny_size template, that's perfectly appropriate. In this case, however, there are at least two disadvantages.
[7] That said, other preprocessors can handle 256 * 256 nested repetitions without any speed problems whatsoever.
The solution to these problems, naturally, is vertical repetition, which generates instances of a pattern across multiple lines. The Preprocessor library provides two means of vertical repetition: local iteration and file iteration.
The most expedient way to demonstrate local iteration in our example is to replace the invocation of BOOST_PP_REPEAT with the following:
#include <boost/preprocessor/iteration/local.hpp> #define BOOST_PP_LOCAL_MACRO(n) TINY_size(~, n, ~) #define BOOST_PP_LOCAL_LIMITS (0, TINY_MAX_SIZE - 1) #include BOOST_PP_LOCAL_ITERATE()
Local iteration repeatedly invokes the user-defined macro with the special name BOOST_PP_LOCAL_MACRO, whose argument will be an iteration index. Since we already had TINY_size lying around, we've just defined BOOST_PP_LOCAL_MACRO to invoke it. The range of iteration indices are given by another user-defined macro, BOOST_PP_LOCAL_LIMITS, which must expand to a parenthesized pair of integer values representing the inclusive range of index values passed to BOOST_PP_LOCAL_MACRO. 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.
Finally, the repetition is initiated by #include-ing the result of invoking BOOST_PP_LOCAL_ITERATE, 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.
If we throw the new example at our preprocessor, we'll see the following, on three separate lines in the output:
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> {};
That represents a great improvement in verifiability, but it's still not ideal. As TINY_MAX_SIZE 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.
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 tiny_size 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, every statement in that generated function occupies that same line.
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 #include-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.
To apply file iteration in our example, we can replace our earlier local iteration code and the definition of TINY_size, with:
#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()
BOOST_PP_ITERATION_LIMITS follows the same pattern as BOOST_PP_LOCAL_LIMITS did, allowing us to specify an inclusive range of iteration indices. BOOST_PP_FILENAME_1 specifies the name of the file to repeatedly #include (we'll show you that file in a moment). The trailing 1 indicates that this is the first nesting level of file iteration—should we need to invoke file iteration again from within tiny_size_spec.hpp, we'd need to use BOOST_PP_FILENAME_2 instead.
The contents of tiny_size_spec.hpp should look familiar to you; most of it is the same as TINY_size's replacement-list, without the backslashes:
#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
The Library transmits the iteration index to us in the result of BOOST_PP_ITERATION(); n is nothing more than a convenient local macro used to reduce syntactic noise. Note that we didn't use #include guards because we need tiny_size_spec.hpp to be processed multiple times.
The preprocessed result should now preserve the line structure of the pattern and be more verifiable for larger values of TINY_MAX_SIZE. For instance, when TINY_MAX_SIZE is 8, the following excerpt appears in the output of GCC's preprocessing phase:
...
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> {};
...etc.
Creating an entirely new file like tiny_size_spec.hpp 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. BOOST_PP_IS_ITERATING 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 tiny_size.hpp file that demonstrates self-iteration. Note in particular the placement and use of the #include guard TINY_SIZE_HPP_INCLUDED:
#ifndef BOOST_PP_IS_ITERATING
# 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 // BOOST_PP_IS_ITERATING
# 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 // BOOST_PP_IS_ITERATING
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 BOOST_PP_ITERATE 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."
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 BOOST_PP_SUB to subtract two numeric tokens in our tiny_size examples. The library contains a suite of operations for non-negative integral token arithmetic in its arithmetic/ subdirectory, as shown in Table A.1
| Expression | Value of Single Token Result |
|---|---|
| BOOST_PP_ADD(x,y) | x + y |
| BOOST_PP_DEC(x) | x - 1 |
| BOOST_PP_DIV(x,y) | x / y |
| BOOST_PP_INC(x) | x + 1 |
| BOOST_PP_MOD(x,y) | x % y |
| BOOST_PP_MUL(x,y) | x * y |
| BOOST_PP_SUB(x,y) | x - y |
The logical/ 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 0 or 1 (a single bit).
| Expression | Value of Single Token Result |
|---|---|
| BOOST_PP_AND(x,y) | x && y |
| BOOST_PP_NOR(x,y) | !(x || y) |
| BOOST_PP_OR(x,y) | x || y |
| BOOST_PP_XOR(x,y) | (bool)x != (bool)y ? 1 : 0 |
| BOOST_PP_NOT(x) | x ? 0 : 1 |
| BOOST_PP_BOOL(x) | x ? 1 : 0 |
| Expression | Value of Single Token Result |
|---|---|
| BOOST_PP_BITAND(x,y) | x && y |
| BOOST_PP_BITNOR(x,y) | !(x || y) |
| BOOST_PP_BITOR(x,y) | x || y |
| BOOST_PP_BITXOR(x,y) | (bool)x != (bool)y ? 1 : 0 |
| BOOST_PP_COMPL(x) | x ? 0 : 1 |
Finally, the comparison/ subdirectory provides the token integral comparison operations shown in Table A.4.
| Expression | Value of Single Token Result |
|---|---|
| BOOST_PP_EQUAL(x,y) | x == y ? 1 : 0 |
| BOOST_PP_NOT_EQUAL(x,y) | x != y ? 1 : 0 |
| BOOST_PP_LESS(x,y) | x < y ? 1 : 0 |
| BOOST_PP_LESS_EQUAL(x,y) | x <= y ? 1 : 0 |
| BOOST_PP_GREATER(x,y) | x > y ? 1 : 0 |
| BOOST_PP_GREATER_EQUAL(x,y) | x >= y ? 1 : 0 |
Because it's common to have a choice among several workable comparison operators, it may be useful to know that BOOST_PP_EQUAL and BOOST_PP_NOT_EQUAL are likely to be O(1) while the other comparison operators are generally slower.
In its control/ directory, the Preprocessor Library supplies a macro BOOST_PP_IF(c,t,f) that fulfills a similar role to the one filled by mpl::if_. To explore the "control" group, we'll generate code for a framework of generic function objects: the Boost Function Library.[8] boost::function is partially specialized to match function type arguments of each arity up to the maximum supported by the library:
template <class Signature> struct function; // primary template template <class R> // arity = 0 struct function<R()> definition not shown... template <class R, class A0> // arity = 1 struct function<R(A0)> definition not shown... template <class R, class A0, class A1> // arity = 2 struct function<R(A0,A1)> definition not shown... template <class R, class A0, class A1, class A2> // arity = 3 struct function<R(A0,A1,A2)> definition not shown... etc.
| [8] | We touched briefly on the design of Boost Function when we discussed type erasure in Chapter 9. See the Function library documentation at boost_1_32_0/libs/function/index.html on the CD that accompanies this book for more information. |
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 tiny_size would be fine:
#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 template <class Signature> struct function; // 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 template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)> struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )> definition not shown... # undef n #endif // BOOST_PP_IS_ITERATING
BOOST_PP_ENUM_TRAILING_PARAMS, used above, is just like BOOST_PP_ENUM_PARAMS except that when its first argument is not 0, it generates a leading comma.
For the sake of interoperability with C++ standard library algorithms, it might be nice if functions of one or two arguments were derived from appropriate specializations of std::unary_function or std::binary_function, respectively.[9] BOOST_PP_IF is a great tool for dealing with special cases:
# 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), : std::binary_function<A0, A1, R>
, BOOST_PP_IF(
BOOST_PP_EQUAL(n,1), : std::unary_function<A0, R>
, ...empty argument...
)
)
{ ...class body omitted... };
| [9] | While derivation from std::unary_function or std::binary_function 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 first_argument_type, second_argument_type, and result_type typedefs directly. |
Well, our first attempt has run into several problems. First off, you're not allowed to pass an empty argument to the preprocessor.[3] Secondly, because angle brackets don't get special treatment, the commas in the std::unary_function and std::binary_function specializations above are treated as macro argument separators, and the preprocessor will complain that we've passed the wrong number of arguments to BOOST_PP_IF in two places.
Because it captures all of the issues, let's focus on the inner BOOST_PP_IF invocation for a moment. The strategy that mpl::eval_if uses, of selecting a nullary function to invoke, could work nicely here. The preprocessor doesn't have a direct analogue for mpl::eval_if, but it doesn't really need one: We can get the right effect by adding a second set of parentheses to BOOST_PP_IF.
#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
)()
#undef BOOST_FUNCTION_empty
#undef BOOST_FUNCTION_unary
A nullary macro that generates nothing is so commonly needed that the library's "facilities" group provides one: BOOST_PP_EMPTY. To complete the example we'll need to delay evaluation all the way to the outer BOOST_PP_IF invocation, because std::binary_function<A0,A1,R> also has a "comma problem":
# include <boost/preprocessor/facilities/empty.hpp>
# 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
, BOOST_PP_EMPTY
)
)()
{
...class body omitted...
};
# undef BOOST_FUNCTION_unary
# undef BOOST_FUNCTION_binary
# undef n
Note that because we happened to be using file iteration, we could have also used #if on n's value directly:
template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
#if n == 2
: std::binary_function<A0, A1, R>
#elif n == 1
: std::unary_function<A0, R>
#endif
BOOST_PP_IF has the advantage of enabling us to encapsulate the logic in a reusable macro, parameterized on n, that is compatible with all repetition constructs:
#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 \
) \
)()
BOOST_PP_IDENTITY, also in the "facilities" group, is an interesting cousin of BOOST_PP_EMPTY:
#define BOOST_PP_IDENTITY(tokens) tokens BOOST_PP_EMPTY
You can think of it as creating a nullary macro that returns tokens: When empty parentheses are appended, the trailing BOOST_PP_EMPTY is expanded leaving just tokens behind. If we had wanted inheritance from mpl::empty_base when function's arity is not one or two, we could have used BOOST_PP_IDENTITY:
// 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
, BOOST_PP_IDENTITY(: mpl::empty_base)
)
)()
{
...class body omitted...
};
It's also worth knowing about BOOST_PP_EXPR_IF, which generates its second argument or nothing, depending on the Boolean value of its first:
#define BOOST_PP_EXPR_IF(c,tokens) \ BOOST_PP_IF(c,BOOST_PP_IDENTITY(tokens),BOOST_PP_EMPTY)()
So BOOST_PP_EXPR_IF(1,foo) expands to foo, while BOOST_PP_EXPR_IF(0,foo) expands to nothing.
It would be nice if there were a generic way to access the return and parameter types of all 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 signature for each function arity:
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> {};
...
To generate these specializations, we might add the following to our pattern:
template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
struct signature<function<R( BOOST_PP_ENUM_PARAMS(n,A) )> >
: mpl::BOOST_PP_CAT(vector,n)<
R BOOST_PP_ENUM_TRAILING_PARAMS(n,A)
> {};
BOOST_PP_CAT implements token pasting; its two arguments are "glued" together into a single token. Since this is a general-purpose macro, it sits in cat.hpp at the top level of the library's directory tree.
Although the preprocessor has a built-in token-pasting operator, ##, it only works within a macro definition. If we'd used it here, it wouldn't have taken effect at all:
template <class R>
struct signature<function<R()> >
: mpl::vector##1<R> {};
template <class R, class A0>
struct signature<function<R(A0)> >
: mpl::vector##2<R,A0> {};
template <class R, class A0, class A1>
struct signature<function<R(A0,A1)> >
: mpl::vector##3<R,A0,A1> {};
...
Also, ## often yields surprising results by taking effect before its arguments have been expanded:
#define N 10 #define VEC(i) vector##i VEC(N) // vectorN
By contrast, BOOST_PP_CAT delays concatenation until after its arguments have been fully evaluated:
#define N 10 #define VEC(i) BOOST_PP_CAT(vector,i) VEC(N) // vector10
The Preprocessor library also provides data types, which you can think of as being analogous to the MPL's type sequences. Preprocessor data types store macro arguments instead of C++ types.
A sequence (or seq for short) is any string of nonempty parenthesized macro arguments. For instance, here's a three-element sequence:
#define MY_SEQ (f(12))(a + 1)(foo)
Here's how we might use a sequence to generate specializations of the is_integral template from the Boost Type Traits library (see Chapter 2):
#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
BOOST_PP_SEQ_FOR_EACH is a higher-order macro, similar to BOOST_PP_REPEAT, that invokes its first argument on each element of its third argument.
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.
The facilities for manipulating sequences are all in the library's seq/ subdirectory. They are summarized in Table A.5, where t is the sequence (t0)(t1)...(tk). Where s, r, and d appear, they have a similar purpose to the z parameters we discussed earlier (and suggested you ignore for now).
| Expression | Result |
|---|---|
| BOOST_PP_SEQ_CAT(t) | t0t1...tk |
| BOOST_PP_SEQ_ELEM(n,t) | tn |
| BOOST_PP_SEQ_ENUM(t) | t0, t1, ...tk |
| BOOST_PP_SEQ_FILTER(pred,data,t) | t without the elements that don't satisfy pred |
| BOOST_PP_SEQ_FIRST_N(n,t) | (t0)(t1)...(tn-1) |
| BOOST_PP_SEQ_FOLD_LEFT(op, x, t) | ...op(s,op(s,op(s,x,t0),t1),t2)... |
| BOOST_PP_SEQ_FOLD_RIGHT(op, x, t) | ...op(s,op(s,op(s,x,tk),tk-1), tk-2)... |
| BOOST_PP_SEQ_FOR_EACH(f, x, t) | f(r, x,t0) f(r, x,t1)...f(r, x,tk) |
| BOOST_PP_SEQ_FOR_EACH_I(g, x, t) | g(r, x, 0, t0) g(r, x, 1, t1)... g(r, x, k, tk) |
| BOOST_PP_SEQ_FOR_EACH_PRODUCT(h, x, t) |
|
| BOOST_PP_SEQ_INSERT(t,i,tokens) | (t0)(t1)...(ti-1)(tokens) (ti)(ti+1)...(tk) |
| BOOST_PP_SEQ_POP_BACK(t) | (t0)(t1)...(tk-1) |
| BOOST_PP_SEQ_POP_FRONT(t) | (t1)(t2)...(tk) |
| BOOST_PP_SEQ_PUSH_BACK(t,tokens) | (t0)(t1)...(tk)(tokens) |
| BOOST_PP_SEQ_PUSH_FRONT(t,tokens) | (tokens)(t0)(t1)...(tk) |
| BOOST_PP_SEQ_REMOVE(t,i) | (t0)(t1)...(ti-1)(ti+1)...(tk) |
| BOOST_PP_SEQ_REPLACE(t,i,tokens) | (t0)(t1)...(ti-1)(tokens)(ti+1)...(tk) |
| BOOST_PP_SEQ_REST_N(n,t) | (tn)(tn+1)...(tk) |
| BOOST_PP_SEQ_REVERSE(t) | (tk)(tk-1)...(t0) |
| BOOST_PP_SEQ_HEAD(t) | t0 |
| BOOST_PP_SEQ_TAIL(t) | (t1)(t2)...(tk) |
| BOOST_PP_SEQ_SIZE(t) | k+1 |
| BOOST_PP_SEQ_SUBSEQ(t,i,m) | (ti)(ti+1)...(ti+m-1) |
| BOOST_PP_SEQ_TO_ARRAY(t) | (k+1 ,(t0,t1,...tk)) |
| BOOST_PP_SEQ_TO_TUPLE(t) | (t0, t1,...tk) |
| BOOST_PP_SEQ_TRANSFORM(f, x, t) | (f(r,x,t0)) (f(r,x,t1))...(f(r,x,tk)) |
It's worth noting that while there is no upper limit on the length of a sequence, operations such as BOOST_PP_SEQ_ELEM that take numeric arguments will only work with values up to 256.
A tuple 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 macro arguments. For example, this is a three-element tuple:
#define TUPLE3 (f(12), a + 1, foo)
The operations in the library's tuple/ subdirectory can handle tuples of up to 25 elements. For example, a tuple's Nth element can be accessed via BOOST_PP_TUPLE_ELEM, as follows:
// length index tuple BOOST_PP_TUPLE_ELEM( 3 , 1 , TUPLE3) // a + 1
Notice that we had to pass the tuple's length as the second argument to BOOST_PP_TUPLE_ELEM; in fact, all 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 BOOST_PP_SEQ_TO_TUPLE, and nonempty tuples can be transformed back into sequences with BOOST_PP_TUPLE_TO_SEQ.
The greatest strength of tuples is that they conveniently take the same representation as a macro argument list:
#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) selector tuple SELECT(THIRD_OF_THREE, TUPLE3) // foo
An array is just a tuple containing a non-negative integer and a tuple of that length:
#define ARRAY3 ( 3, TUPLE3 )
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:
BOOST_PP_ARRAY_ELEM(1, ARRAY3) // a + 1
The facilities for manipulating arrays of up to 25 elements are all in the library's array/ subdirectory. They are summarized in Table A.6, where a is the array (k, (a0,a1,...ak-1)).
| Expression | Result |
|---|---|
| BOOST_PP_ARRAY_DATA(a) | (a0,a1,... ak-1) |
| BOOST_PP_ARRAY_ELEM(i,a) | ai |
| BOOST_PP_ARRAY_INSERT(a, i, tokens) | (k+1,(a0,a1,...ai-1, tokens, ai,ai+1,... ak-1)) |
| BOOST_PP_ARRAY_POP_BACK(a) | (k-1,(a0,a1,... ak-2)) |
| BOOST_PP_ARRAY_POP_FRONT(a) | (k-1,(a1,a2,... ak-1)) |
| BOOST_PP_ARRAY_PUSH_BACK(a, tokens) | (k+1,(a0,a1,... ak-1, tokens)) |
| BOOST_PP_ARRAY_PUSH_FRONT(a, tokens) | (k+1,(tokens, a1,a2,... ak-1)) |
| BOOST_PP_ARRAY_REMOVE(a, i) | (k-1,(a0,a1,... ai-1,ai+1,... ak-1)) |
| BOOST_PP_ARRAY_REPLACE(a, i, tokens) | (k,(a0,a1,... ai-1, tokens, ai+1,... ak-1)) |
| BOOST_PP_ARRAY_REVERSE(a) | (k,(ak-1,ak-2,... a1,a0)) |
| BOOST_PP_ARRAY_SIZE(a) | k |
A list 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 BOOST_PP_NIL if there are no remaining elements. Lists have access characteristics similar to those of a runtime linked list. Here is a three-element list:
#define LIST3 (f(12), (a + 1, (foo, BOOST_PP_NIL)))
The facilities for manipulating lists are all in the library's list/ 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.
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.