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

Updated docs for the the fact that in C++20 mode when __VA_OPT__ is supported variadic data passed some of the variadic macros can be empty.

Browse Source
This commit is contained in:
Edward Diener
2020-06-30 14:50:47 -04:00
parent a037024cec
commit e231fe7ad9
7 changed files with 448 additions and 384 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
doc/ref/array_enum.html
View File

@ -1,37 +1,52 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1252">
<title>BOOST_PP_ARRAY_ENUM</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_ARRAY_ENUM</b> macro converts an <i>array</i> to its comma-separated elements. The comma-separated elements are in the form of <i>variadic data</i>.<br>
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_ARRAY_ENUM</b>
macro converts an <i>array</i> to its comma-separated elements.
The comma-separated elements are in the form of <i>variadic data</i>.<br>
</div>
<h4> Usage </h4>
<div class="code"> <b>BOOST_PP_ARRAY_ENUM</b>(<i>array</i>) </div>
<h4> Arguments </h4>
<dl>
<h4> Usage </h4>
<div class="code"> <b>BOOST_PP_ARRAY_ENUM</b>(<i>array</i>) </div>
<h4> Arguments </h4>
<dl>
<dt>array</dt>
<dd> The <i>array</i> whose elements are to be converted. </dd>
</dl>
<h4> Remarks </h4>
<div> This macro expands to a comma-separated list of the elements in <i>array</i>.&nbsp;
For example, <b>BOOST_PP_ARRAY_ENUM</b>((3,(<i>x,</i><i>y,</i><i>z</i>)))
expands to...
<div> <i>x</i>, <i>y</i>, <i>z</i> </div>
</div>
<h4> Requirements </h4>
<div> <b>Header:</b> &nbsp;<a href="../headers/array/enum.html">&lt;boost/preprocessor/array/enum.hpp&gt;</a>
</div>
<h4> Sample Code </h4>
<div>
<pre>#include &lt;<a href="../headers/array/enum.html">boost/preprocessor/array/enum.hpp</a>&gt;<br><br>#define ARRAY (5,(B,O,O,S,T))<br><br><a href="array_enum.html">BOOST_PP_ARRAY_ENUM</a>(ARRAY) // expands to B, O, O, S, T<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><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>
</dl>
<h4> Remarks </h4>
<div> This macro expands to a comma-separated list of the elements
in <i>array</i>.&nbsp;
For example, <b>BOOST_PP_ARRAY_ENUM</b>((3,(<i>x,</i><i>y,</i><i>z</i>)))
expands
to...
<div> <i>x</i>, <i>y</i>, <i>z<br>
</i> </div>
</div>
<p>&nbsp;&nbsp;&nbsp; In <a
href="file:///E:/Programming/VersionControl/modular-boost/libs/preprocessor/doc/topics/variadic_macros.html#C20_Support_For_Variadic_Macros">C++
20</a> mode if the array is empty the resulting <i>variadic</i>
<i>data</i> will be empty.</p>
<h4> </h4>
<h4>Requirements </h4>
<div> <b>Header:</b> &nbsp;<a href="../headers/array/enum.html">&lt;boost/preprocessor/array/enum.hpp&gt;</a>
</div>
<h4> Sample Code </h4>
<div>
<pre>#include &lt;<a href="../headers/array/enum.html">boost/preprocessor/array/enum.hpp</a>&gt;<br><br>#define ARRAY (5,(B,O,O,S,T))<br><br><a href="array_enum.html">BOOST_PP_ARRAY_ENUM</a>(ARRAY) // expands to B, O, O, S, T<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><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>

74
doc/ref/list_enum.html
View File

@ -1,62 +1,62 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1252">
<title>BOOST_PP_LIST_ENUM</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
</head>
<body>
<div style="margin-left: 0px;">
The <b>BOOST_PP_LIST_ENUM</b> macro converts a <i>list</i> to a comma-separated list.
</div>
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_LIST_ENUM</b> macro
converts a <i>list</i> to a comma-separated list. </div>
<h4>Usage</h4>
<div class="code">
<b>BOOST_PP_LIST_ENUM</b>(<i>list</i>)
</div>
<div class="code"> <b>BOOST_PP_LIST_ENUM</b>(<i>list</i>) </div>
<h4>Arguments</h4>
<dl>
<dt>list</dt>
<dd>
The <i>list</i> to be converted.
</dd>
<dd> The <i>list</i> to be converted. </dd>
</dl>
<h4>Remarks</h4>
<div>
If <i>list</i> is, for example, (<i>a</i>, (<i>b</i>, (<i>c</i>, <b>BOOST_PP_NIL</b>))),
this macro will produce:
<div>
<i>a</i>, <i>b</i>, <i>c</i>
</div>
</div>
<div>
Previously, this macro could not be used inside <b>BOOST_PP_FOR</b>.&nbsp;
There is no longer any such restriction.&nbsp;
It is more efficient, however, to use <b>BOOST_PP_LIST_ENUM_R</b> in such a situation.
<div> If <i>list</i> is, for example, (<i>a</i>, (<i>b</i>, (<i>c</i>,
<b>BOOST_PP_NIL</b>))), this macro will produce:
<div> <i>a</i>, <i>b</i>, <i>c</i> </div>
</div>
<div> Previously, this macro could not be used inside <b>BOOST_PP_FOR</b>.&nbsp;
There is no longer any such restriction.&nbsp; It is more
efficient, however, to use <b>BOOST_PP_LIST_ENUM_R</b> in such a
situation.<br>
<br>
In <a
href="file:///E:/Programming/VersionControl/modular-boost/libs/preprocessor/doc/topics/variadic_macros.html#C20_Support_For_Variadic_Macros">C++
20</a> mode if the list is empty the resulting <i>variadic</i>
<i>data</i> will be empty.</div>
<h4>See Also</h4>
<ul>
<li><a href="list_enum_r.html">BOOST_PP_LIST_ENUM_R</a></li>
</ul>
<h4>Requirements</h4>
<div>
<b>Header:</b> &nbsp;<a href="../headers/list/enum.html">&lt;boost/preprocessor/list/enum.hpp&gt;</a>
<div> <b>Header:</b> &nbsp;<a href="../headers/list/enum.html">&lt;boost/preprocessor/list/enum.hpp&gt;</a>
</div>
<h4>Sample Code</h4>
<div><pre>
#include &lt;<a href="../headers/list/enum.html">boost/preprocessor/list/enum.hpp</a>&gt;
<div>
<pre>#include &lt;<a href="../headers/list/enum.html">boost/preprocessor/list/enum.hpp</a>&gt;
#define LIST (w, (x, (y, (z, <a href="nil.html">BOOST_PP_NIL</a>))))
<a href="list_enum.html">BOOST_PP_LIST_ENUM</a>(LIST) // expands to w, x, y, z
</pre></div>
</pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i><EFBFBD> Copyright <a
href="http://www.housemarque.com" target="_top">Housemarque Oy</a>
2002</i> <br>
<i><EFBFBD> Copyright Paul Mensonides 2002</i> </div>
<div style="margin-left: 0px;">
<i><EFBFBD> Copyright <a href="http://www.housemarque.com" target="_top">Housemarque Oy</a> 2002</i>
</br><i><EFBFBD> Copyright Paul Mensonides 2002</i>
<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>
<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>
</body>
</html>

6
doc/ref/list_enum_r.html
View File

@ -31,6 +31,12 @@
<i>a</i>, <i>b</i>, <i>c</i>
</div>
</div>
<div>
In <a
href="file:///E:/Programming/VersionControl/modular-boost/libs/preprocessor/doc/topics/variadic_macros.html#C20_Support_For_Variadic_Macros">C++
20</a> mode if the list is empty the resulting <i>variadic</i>
<i>data</i> will be empty.
</div>
<h4>See Also</h4>
<ul>
<li><a href="list_enum.html">BOOST_PP_LIST_ENUM</a></li>

67
doc/ref/variadic_size.html
View File

@ -1,33 +1,46 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1252">
<title>BOOST_PP_VARIADIC_SIZE</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_VARIADIC_SIZE</b> variadic macro
expands to the size of the <i>variadic data </i>passed to it. </div>
<h4>Usage</h4>
<div class="code"> <b>BOOST_PP_VARIADIC_SIZE</b>(<i>...</i>) <a href="../topics/variadic_macros.html#VNotation" target="_self"><sup>(v)</sup></a><br>
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_VARIADIC_SIZE</b>
variadic macro
expands to the size of the <i>variadic data </i>passed to it. </div>
<h4>Usage</h4>
<div class="code"> <b>BOOST_PP_VARIADIC_SIZE</b>(<i>...</i>) <a
href="../topics/variadic_macros.html#VNotation" target="_self"><sup>(v)</sup></a><br>
</div>
<h4>Arguments</h4>
<dl>
<h4>Arguments</h4>
<dl>
<dt>...<br>
</dt>
<dd>&nbsp; <i>Variadic data </i>whose size is to be extracted. </dd>
</dl>
<h4>Requirements</h4>
<div> <b>Header:</b> &nbsp;<a href="../headers/variadic/size.html">&lt;boost/preprocessor/variadic/size.hpp&gt;</a>
</div>
<h4>Sample Code</h4>
<div>
<pre>#include &lt;<a href="../headers/variadic/size.html">boost/preprocessor/variadic/size.hpp</a>&gt;<br><br>#define VAR_DATA x, y, z<br><br><a href="variadic_size.html">BOOST_PP_VARIADIC_SIZE</a>(VAR_DATA) // expands to 3<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><i><EFBFBD> Copyright Edward Diener 2011,2013</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>
</dt>
<dd>&nbsp; <i>Variadic data </i>whose size is to be extracted.</dd>
</dl>
<h4>Remarks</h4>
<p>&nbsp;&nbsp;&nbsp; In <a
href="../topics/variadic_macros.html#C20_Support_For_Variadic_Macros">C++
20</a> mode the <i>variadic</i> <i>data</i> can be empty and
the result will be 0.<br>
</p>
<h4>Requirements</h4>
<div> <b>Header:</b> &nbsp;<a href="../headers/variadic/size.html">&lt;boost/preprocessor/variadic/size.hpp&gt;</a>
</div>
<h4>Sample Code</h4>
<div>
<pre>#include &lt;<a href="../headers/variadic/size.html">boost/preprocessor/variadic/size.hpp</a>&gt;<br><br>#define VAR_DATA x, y, z<br><br><a href="variadic_size.html">BOOST_PP_VARIADIC_SIZE</a>(VAR_DATA) // expands to 3<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><i><EFBFBD> Copyright Edward Diener
2011,2013</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>

65
doc/ref/variadic_to_array.html
View File

@ -1,32 +1,45 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1252">
<title>BOOST_PP_VARIADIC_TO_ARRAY</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_VARIADIC_TO_ARRAY</b> variadic macro
converts <i>variadic data</i> to an <i>array</i>. </div>
<h4> Usage </h4>
<div class="code"> <b>BOOST_PP_VARIADIC_TO_ARRAY</b>(<i>...</i>) <a href="../topics/variadic_macros.html#VNotation" target="_self"><sup>(v)</sup></a><br>
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_VARIADIC_TO_ARRAY</b>
variadic macro
converts <i>variadic data</i> to an <i>array</i>. </div>
<h4> Usage </h4>
<div class="code"> <b>BOOST_PP_VARIADIC_TO_ARRAY</b>(<i>...</i>) <a
href="../topics/variadic_macros.html#VNotation" target="_self"><sup>(v)</sup></a><br>
</div>
<h4> Arguments </h4>
<dl>
<h4> Arguments </h4>
<dl>
<dt>...</dt>
<dd> The <i>variadic data</i> to be converted. </dd>
</dl>
<h4> Requirements </h4>
<div> <b>Header:</b> &nbsp;<a href="../headers/variadic/to_array.html">&lt;boost/preprocessor/variadic/to_array.hpp&gt;</a>
</div>
<h4> Sample Code </h4>
<div>
<pre>#include &lt;<a href="../headers/variadic/to_array.html">boost/preprocessor/variadic/to_array.hpp</a>&gt;<br><br>#define VAR_DATA a, b, c<br><br><a href="variadic_to_array.html">BOOST_PP_VARIADIC_TO_ARRAY</a>(VAR_DATA) // expands to (3, (a, b, c))<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><i><EFBFBD> Copyright Edward Diener 2011,2013</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>
<dd> The <i>variadic data</i> to be converted.</dd>
</dl>
<h4>Remarks</h4>
<p>&nbsp;&nbsp;&nbsp; In <a
href="file:///E:/Programming/VersionControl/modular-boost/libs/preprocessor/doc/topics/variadic_macros.html#C20_Support_For_Variadic_Macros">C++
20</a> mode the <i>variadic</i> <i>data</i> can be empty and
the result will be an empty array of the form '(0,())'.</p>
<h4> Requirements </h4>
<div> <b>Header:</b> &nbsp;<a
href="../headers/variadic/to_array.html">&lt;boost/preprocessor/variadic/to_array.hpp&gt;</a>
</div>
<h4> Sample Code </h4>
<div>
<pre>#include &lt;<a href="../headers/variadic/to_array.html">boost/preprocessor/variadic/to_array.hpp</a>&gt;<br><br>#define VAR_DATA a, b, c<br><br><a href="variadic_to_array.html">BOOST_PP_VARIADIC_TO_ARRAY</a>(VAR_DATA) // expands to (3, (a, b, c))<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><i><EFBFBD> Copyright Edward Diener
2011,2013</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>

64
doc/ref/variadic_to_list.html
View File

@ -1,31 +1,45 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<head>
<meta http-equiv="content-type" content="text/html; charset=windows-1252">
<title>BOOST_PP_VARIADIC_TO_LIST</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_VARIADIC_TO_LIST</b>
variadic macro converts <i>variadic data</i> to a <i>list</i>. </div>
<h4>Usage</h4>
<div class="code"> <b>BOOST_PP_VARIADIC_TO_LIST</b>(<i>...</i>) <a href="../topics/variadic_macros.html#VNotation" target="_self"><sup>(v)</sup></a><br>
</head>
<body>
<div style="margin-left: 0px;"> The <b>BOOST_PP_VARIADIC_TO_LIST</b>
variadic macro converts <i>variadic data</i> to a <i>list</i>. </div>
<h4>Usage</h4>
<div class="code"> <b>BOOST_PP_VARIADIC_TO_LIST</b>(<i>...</i>) <a
href="../topics/variadic_macros.html#VNotation" target="_self"><sup>(v)</sup></a><br>
</div>
<h4>Arguments</h4>
<dl><dt>...</dt>
<h4>Arguments</h4>
<dl>
<dt>...</dt>
<dd> The <i>variadic data</i> to be converted.<br>
</dd>
</dl><h4>Requirements</h4>
<div> <b>Header:</b> &nbsp;<a href="../headers/variadic/to_list.html">&lt;boost/preprocessor/variadic/to_list.hpp&gt;</a>
</div>
<h4>Sample Code</h4>
<div>
<pre>#include &lt;<a href="../headers/variadic/to_list.html">boost/preprocessor/variadic/to_list.hpp</a>&gt;<br><br><a href="variadic_to_list.html">BOOST_PP_VARIADIC_TO_LIST</a>(x, y, z)<br> // expands to (x, (y, (z, <a href="nil.html">BOOST_PP_NIL</a>)))<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><i><EFBFBD> Copyright Edward Diener 2011,2013</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>
</dd>
</dl>
<h4>Remarks</h4>
<p>&nbsp;&nbsp;&nbsp; In <a
href="file:///E:/Programming/VersionControl/modular-boost/libs/preprocessor/doc/topics/variadic_macros.html#C20_Support_For_Variadic_Macros">C++
20</a> mode the <i>variadic</i> <i>data</i> can be empty and
the result will be an empty list of the form 'BOOST_PP_NIL'.</p>
<h4>Requirements</h4>
<div> <b>Header:</b> &nbsp;<a
href="../headers/variadic/to_list.html">&lt;boost/preprocessor/variadic/to_list.hpp&gt;</a>
</div>
<h4>Sample Code</h4>
<div>
<pre>#include &lt;<a href="../headers/variadic/to_list.html">boost/preprocessor/variadic/to_list.hpp</a>&gt;<br><br><a href="variadic_to_list.html">BOOST_PP_VARIADIC_TO_LIST</a>(x, y, z)<br> // expands to (x, (y, (z, <a href="nil.html">BOOST_PP_NIL</a>)))<br></pre>
</div>
<hr size="1">
<div style="margin-left: 0px;"> <i></i><i><EFBFBD> Copyright Edward Diener
2011,2013</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>

371
doc/topics/variadic_macros.html
View File

@ -1,6 +1,8 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=windows-1252" http-equiv="content-type">
<meta content="text/html; charset=windows-1252"
http-equiv="content-type">
<title>variadic_macros.html</title>
<link rel="stylesheet" type="text/css" href="../styles.css">
<style>
@ -9,258 +11,260 @@
</head>
<body>
<h4>Variadic Macros</h4>
<div> Variadic macros are supported by a number of compilers. They are
macros of the form: </div>
<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__</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>
<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>
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>
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)</pre>
</div>
<u> <span style="font-weight: bold;">Preprocessor
Library Support<br>
<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>
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>
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>
<a name="vmvcquirk"></a>Visual C++ has a
few quirks related to variadic macros which require the end-user to code
slightly differently. When BOOST_PP_VARIADICS is 1 and Visual C++ is the
compiler BOOST_PP_VARIADICS_MSVC is 1, else when BOOST_PP_VARIADICS is 1
and Visual C++ is not the compiler BOOST_PP_VARIADICS_MSVC is 0. When
BOOST_PP_VARIADICS is 0 then BOOST_PP_VARIADICS_MSVC is not defined.
In this way the end-user, when using variadic macros, can test for the
presence of Visual C++ as the compiler and code accordingly.<br>
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>
<a name="vmvcquirk"></a>Visual C++ has a few quirks related to
variadic macros which require the end-user to code slightly
differently. When BOOST_PP_VARIADICS is 1 and Visual C++ is the
compiler BOOST_PP_VARIADICS_MSVC is 1, else when
BOOST_PP_VARIADICS is 1 and Visual C++ is not the compiler
BOOST_PP_VARIADICS_MSVC is 0. When BOOST_PP_VARIADICS is 0 then
BOOST_PP_VARIADICS_MSVC is not defined. In this way the end-user,
when using variadic macros, can test for the presence of Visual
C++ as the compiler and code accordingly.<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>
<a name="VNotation"></a>
<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.
</div>
<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. </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>
<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>
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>
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>
<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
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>
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,
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>
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>
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>
<h4>C++20 Support For Variadic Macros</h4>
<div>
In the C++20 specification there is a new construct which can be
used in the expansion of a variadic macro, called __VA_OPT__. This
construct when used in the expansion of a variadic macro is followed
by an opening paranthesis ('('), preprocessor data, and a closing
parenthesis ('}'). When the variadic data passed by the invocation
of a variadic macro is empty, this new construct expands to nothing.
When the variadic data passed by the invocation of a variadic macro
is not empty, this new construct expands to the preprocessor data
between its opening and closing parentheses.
<br><br>
This library offers support for this new C++20 construct by automatically
detecting whether this new construct is supported by the compiler's
preprocessor when using the library. The library macro which detects
support for the __VA_OPT__ construct is called BOOST_PP_VARIADIC_HAS_OPT.
This is a function-like macro which takes no parameters and returns
1 if the compiler is working in C++20 mode and supports the __VA_OPT__
construct, while otherwise it returns 0.
<h4><a name="C20_Support_For_Variadic_Macros"></a>C++20 Support For
Variadic Macros</h4>
<div> In the C++20 specification there is a new construct which can
be used in the expansion of a variadic macro, called __VA_OPT__.
This construct when used in the expansion of a variadic macro is
followed by an opening paranthesis ('('), preprocessor data, and a
closing parenthesis ('}'). When the variadic data passed by the
invocation of a variadic macro is empty, this new construct
expands to nothing. When the variadic data passed by the
invocation of a variadic macro is not empty, this new construct
expands to the preprocessor data between its opening and closing
parentheses. <br>
<br>
This library offers support for this new C++20 construct by
automatically detecting whether this new construct is supported by
the compiler's preprocessor when using the library. The library
macro which detects support for the __VA_OPT__ construct is called
BOOST_PP_VARIADIC_HAS_OPT. This is a function-like macro which
takes no parameters and returns 1 if the compiler is working in
C++20 mode and supports the __VA_OPT__ construct, while otherwise
it returns 0. <br>
<br>
When the __VA_OPT__ construct is supported in C++20 mode the
variadic data passed to the variadic macros can be empty,
otherwise when not in this mode variadic data passed to the
variadic macros should never be empty. In this C+++20 mode
invoking BOOST_PP_VARIADIC_SIZE with empty data expands to 0,
invoking BOOST_PP_VARIADIC_TO_ARRAY with empty data expands to the
empty array '(0,())', and invoking BOOST_PP_VARIADIC_TO_LIST with
empty data expands to the empty list 'BOOST_PP_NIL'. Similarly in
this C++20 mode passing an empty array '(0,())' to
BOOST_PP_ARRAY_ENUM expands to empty variadic data and passing an
empty list 'BOOST_PP_NIL' to BOOST_PP_LIST_ENUM also expands to
empty variadic data. Neither a seq or a tuple can be empty so
passing empty variadic data to either BOOST_PP_VARIADIC_TO_SEQ or
BOOST_PP_VARIADIC_TO_TUPLE is erroneous. Likewise passing empty
data to BOOST_PP_VARIADIC_ELEM is always erroneous since there are
no tokens of variadic data to access. <br>
</div>
<u style="font-weight: bold;"> Using a Tuple Instead of an Array<br>
</u>
<div>An array as a preprocessor data type is a two-element tuple where the
first element is the array size and the second element is a tuple which
constitutes the array data. Because a tuple knows its own size when the
compiler supports variadic macros, there is no reason to use the array preprocessor
data type as opposed to the tuple preprocessor data type; the tuple data
type now has all of the functionality which the array data type has and is
syntactically easier to use. With variadic macro support, which is now
officially part of the latest C++ standard, the preprocessor array data
type is essentially obsolete for conforming C++ compilers. Only if your
compiler does not support variadic macros is the preprocessor array data
type still useful.</div>
<div>An array as a preprocessor data type is a two-element tuple
where the first element is the array size and the second element
is a tuple which constitutes the array data. Because a tuple knows
its own size when the compiler supports variadic macros, there is
no reason to use the array preprocessor data type as opposed to
the tuple preprocessor data type; the tuple data type now has all
of the functionality which the array data type has and is
syntactically easier to use. With variadic macro support, which is
now officially part of the latest C++ standard, the preprocessor
array data type is essentially obsolete for conforming C++
compilers. Only if your compiler does not support variadic macros
is the preprocessor array data type still useful.</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
<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>
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>
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 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<6F> __VA_ARGS__, may fail with certain compilers.<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>
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
<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));</pre>
<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));</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>
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
<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>
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>
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>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>
<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>
@ -269,14 +273,13 @@
<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
<div style="margin-left: 0px;"> <i><EFBFBD> Copyright Edward Diener
2011,2013,2016</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>
<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>