feedc0de/boost_preprocessor
1
0
Fork 0
forked from boostorg/preprocessor
Code Pull Requests Activity

limited variadic support

Browse Source 
[SVN r72763]
This commit is contained in:
Paul Mensonides
2011-06-26 13:07:20 +00:00
parent 0c87b91f95
commit 1149d38ef4
132 changed files with 5004 additions and 1684 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
doc/topics/variadic_macros.html Normal file
View File

@ -0,0 +1,242 @@
<html>
<head>
<title>variadic_macros.html</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
<style>
u { font-weight: normal; text-decoration: none; }
</style>
</head>
<body>
<h4>Variadic Macros</h4>
<div> Variadic macros are supported by a number of compilers.
They are
macros of the form:
</div>
<div class="code">
<pre>#define SOME_MACRO(ZeroOrMoreParameters,...) macro expansion possible specifying __VA_ARGS__<br></pre>
</div>
<div> The '...' in the parameter list represents the variadic
data when the macro is invoked and the __VA_ARGS__ in the expansion
represents the variadic data in the expansion of the macro. Variadic
data is of the form of 1 or more preprocessor tokens separated by
commas.<br>
<br>
The '...' must be the last parameter in the macro definition and there
may be 0 or more non-variadic parameters preceding it.<br>
<br>
In the expansion of the macro __VA_ARGS__ may be specified 0 or more
times to represent the variadic data. The variadic data in the
expansion is a comma separated list of preprocessor tokens representing
the variadic data which the invoker of the macro enters as the last
arguments to the macro.<br>
</div>
<h4>Example<u> - Creating and invoking a variadic macro.</u></h4>
<div class="code">
<pre>#define INITIALIZE_INT_ARRAY(array_name,...) \ <br> static int array_name[] = { __VA_ARGS__ }; \ <br> /**/<br><br> INITIALIZE_INT_ARRAY(myname,45,789,33510,9346,2)<br></pre>
</div>
<u> <span style="font-weight: bold;">Preprocessor
Library Support<br>
</span></u>
<div>The library offers support for variadic macros for those
compilers
which support the feature. The library can automatically detect whether
a compiler supports variadic macros and sets the macro
BOOST_PP_VARIADICS accordingly to 1 if the compiler supports variadic
macros or 0 if the compiler does not support variadic macros.<br>
<br>
The end-user can #define BOOST_PP_VARIADICS to 1 or 0 himself in a
translation unit, before including any preprocessor header files, to
prevent the library from attempting to detect whether the compiler
supports variadic macros. This has the effect of manually turning on or
off variadic macro support in the library. Of course if one manually
turns on variadic macro support in the library, and one's compiler does
not support variadic macros, functionality in the library which uses
variadic macros will fail with error messages from the compiler.<br>
<br>
When BOOST_PP_VARIADICS is 1, the library offers some extended
functionality
by using variadic macros, and also offers extended support for working
with variadic data.<br>
<br>
Support for working with variadic
data is largely centered on being able to convert variadic data to
other library data types, since the
functionality for working with those Boost preprocessor library data
types is much greater than that for working with variadic data directly.<br>
</div>
<h4>Notation For Variadic Macros<br>
</h4>
<div>In the documentation, headers which have variadic macros,
and
variadic macros themselves, have a notation of '(v)' appended to them.
For the variadic macros themselves this signifies that
BOOST_PP_VARIADICS must be 1 for those variadic macros to be usable.
For variadic macros which have a non-variadic equivalent, the
non-variadic equivalent will be used if BOOST_PP_VARIADICS is set to 0
and the non-variadic version of the
macro does not have a '(v)' appended to its name in the documentation.
</div>
<h4>Extended Functionality Using Variadic Macros<br>
</h4>
<div>Some macros in the library offer extended
functionality through the use of variadic macros.<br>
<br>
The variadic macro version offers the same functionality
as the non-variadic version, but because of the ability of the variadic
parameters to encompass a variable number of arguments, it also offers
an enhanced syntax using the same macro name.<br>
<br>
The macros in the library which offer this enhanced functionality are
all
centered on <i>tuple</i> manipulation. With variadic
macros it is
possible to
manipulate tuples without having to know the size of the tuple. So
while the invoker can still specify the size when using tuple macro
functionality, there are variadic versions of each of the tuple macros,
with the exact same name as the non-variadic macro, where the size need
not be specified.<br>
</div>
<h4>Extended Support For Variadic Data</h4>
<div>The library offers extended support for working with
variadic data
which goes beyond the functionality offered by the C++ specification
for variadic macros. It does this through preprocessor programming and
by using some of the other functionality in the library itself. Header
and macro names
in the library which offer extended support for working with variadic
data, and need the compiler to support variadic macros, are marked with
a (v)<sup> </sup>to indicate a variadic macro.<br>
<br>
The form of the functionality which the library offers is centered on
two macros which work with variadic data itself, and a set of macros
which convert between variadic data and other library data
types.<br>
<br>
The two macros are BOOST_PP_VARIADIC_ELEM and BOOST_PP_VARIADIC_SIZE,
which respectively return a particular token of variadic data and the
number of tokens of variadic data.<br>
<br>
The macros for converting variadic data to the library's data types are
BOOST_PP_VARIADIC_TO_ARRAY, BOOST_PP_VARIADIC_TO_LIST,
BOOST_PP_VARIADIC_TO_SEQ, and BOOST_PP_VARIADIC_TO_TUPLE.<br>
<br>
All of these macros need compiler support for variadic data and only
exist if BOOST_PP_VARIADICS is 1. <br>
<br>
The remaining four macros, which convert from a library data type
to comma-separated preprocessor tokens, which is the form of
variadic data, do not need compiler support for variadic
macros. These functions are BOOST_PP_ARRAY_ENUM, BOOST_PP_LIST_ENUM,
BOOST_PP_SEQ_ENUM, and BOOST_PP_TUPLE_ENUM. However if one wishes to
use this variadic data reliably as arguments to other macros, one needs
variadic macro support.<br>
</div>
<u style="font-weight: bold;"> Using Variadic Data</u>
<div>Variadic data exists in the
form of comma-separated preprocessor tokens. This is the case whether
the variadic data comes from the __VA_ARGS__ of a variadic macro, from
the conversion of a library's data type to variadic data, or the
manual construction of comma-separated preprocessing tokens by the
programmer writing a macro.<br>
<br>
The easiest way to work with
variadic data internally is to convert it to a library data type.
Library data types, whether an <i>array</i>, <i>list</i>,
<i>sequence</i>,
or <i>tuple</i>, have a rich set of functionality for
manipulating
data whereas
variadic data functionality in the library only allows one to access
the variadic data as a whole or to access a single token of the
variadic data at a time.<br>
<br>
The user of the library still may
choose to pass variadic data back into internal macros rather than
convert it to other library data types. There is no problem passing
variadic data as a whole to variadic macros as the last parameter of
the macro. However: <br>
<br>
<span style="font-weight: bold;">Attempting to pass
variadic data as a
whole directly into a non-variadic macro is not guaranteed to work and
may fail.<br>
</span><br>
This occurs because of a preprocessor weakness in a number
of compilers, currently most notably Visual C++. Even passing variadic
data as arguments to a non-variadic macro, when it is not represented
in
the form of&nbsp; __VA_ARGS__, may fail with certain compilers.<br>
<br>
What follows are very simple examples, showing how variadic data can be
passed to a non-variadic macro.<br>
<br>
First an example of what NOT to do.<br>
</div>
<h4>Example<u> - Passing variadic data as a whole to a
non-variadic
macro. DO NOT DO.</u></h4>
<div class="code">
<pre>#define MACRO_ARG_2(x,y) BOOST_PP_ADD(x,y)<br>#define VAR_MACRO(...) __VA_ARGS__<br><br>/* The following should not be done and is not guaranteed to work with compilers. */<br><br><span style="font-weight: bold;"><span style="font-family: monospace;"></span></span>int xx = MACRO_ARG_2(VAR_MACRO(2,3));<br></pre>
</div>
<div> There are two ways to pass variadic data to a non-variadic
macro.
The
first of these is to pass the individual tokens of the variadic data
separately to the non-variadic macro using the BOOST_PP_VARIADIC_ELEM
macro in the library.<br>
</div>
<h4>Example<u> - Passing individual variadic data tokens to
a
non-variadic macro.<br>
</u></h4>
<div class="code">
<pre>#define MACRO_ARG_2(x,y) BOOST_PP_ADD(x,y)<br>#define VAR_MACRO(...) __VA_ARGS__<br><br>/* The following will work correctly */<br><br>int xx = MACRO_ARG_2<br> (<br> BOOST_PP_VARIADIC_ELEM(0,VAR_MACRO(2,3)),<br> BOOST_PP_VARIADIC_ELEM(1,VAR_MACRO(2,3))<br> );</pre>
</div>
<div>The second way is to use a macro in the library called
BOOST_PP_OVERLOAD.
This macro allows one to "overload" a variadic macro to non-variadic
macros of different numbers of parameters, using a common prefix.
</div>
<h4>Example<u> - Passing variadic data as a whole to
BOOST_PP_OVERLOAD
and on to a non-variadic macro.<br>
</u></h4>
<div class="code">
<pre>#define MACRO_ARG_2(x,y) BOOST_PP_ADD(x,y)<br>#define VAR_MACRO(...) __VA_ARGS__<br><br>/* The following will work correctly */<br><br>int xx = BOOST_PP_OVERLOAD(MACRO_ARG_,VAR_MACRO(2,3))(VAR_MACRO(2,3));<br><br>/* For Visual C++ it is necessary to do this */<br><br>int xx = <br>BOOST_PP_CAT(BOOST_PP_OVERLOAD(MACRO_ARG_,VAR_MACRO(2,3))(VAR_MACRO(2,3)),BOOST_PP_EMPTY());</pre>
</div><br>
<div>Although these techniques will work when passing variadic
data to
non-variadic macros, it is much better and less problematical to
work internally with the existing library data types and to only use
variadic
macros as an interface for end-users when there is a need to have a
macro which takes a
variable number of parameters.<br>
</div>
<b>See</b> <b>Also</b><br>
<ul>
<li><a href="../ref/variadics.html">BOOST_PP_VARIADICS</a></li>
<li><a href="../headers/tuple.html">Tuple Macros</a><br>
</li>
<li><a href="../headers/variadic.html">Variadic
Macros<br>
</a></li>
<li><a href="../ref/array_enum.html">BOOST_PP_ARRAY_ENUM</a></li>
<li><a href="../ref/list_enum_r.html">BOOST_PP_LIST_ENUM</a></li>
<li><a href="../ref/seq_enum.html">BOOST_PP_SEQ_ENUM</a></li>
<li><a href="../ref/tuple_enum.html">BOOST_PP_TUPLE_ENUM</a></li>
<li><a href="../ref/overload.html">BOOST_PP_OVERLOAD</a></li>
</ul>
<hr size="1">
<div style="margin-left: 0px;"> <i><EFBFBD> Copyright
Edward Diener
2011</i> </div>
<div style="margin-left: 0px;">
<p><small>Distributed under the Boost Software License,
Version 1.0.
(See accompanying file <a href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a>
or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</small></p>
</div>
</body>
</html>