libs/preprocessor/doc/ref/va_opt.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3   <head>
   4     <meta http-equiv="content-type" content="text/html;
   5       charset=windows-1252">
   6     <title>BOOST_PP_VA_OPT</title>
   7     <link rel="stylesheet" type="text/css" href="../styles.css">
   8   </head>
   9   <body>
  10     <div style="margin-left: 0px;"> The <b>BOOST_PP_VA_OPT</b> variadic
  11       macro is a more flexible alternative to the C++20 __VA_OPT__
  12       construct. It expands to either one of two inputs depending on
  13       whether the variadic data is empty or not, whereas the C++20
  14       __VA_OPT__ constructs expands to either its input or nothing
  15       depending on whether the variadic data is empty or not. This macro
  16       only exists when the compilation is at the C++20 level and the
  17       __VA_OPT__ construct is supported.</div>
  18     <h4>Usage</h4>
  19     <div class="code"> <b>BOOST_PP_VA_OPT</b>(x,y,<i>...</i>) <a
  20         href="../topics/variadic_macros.html#VNotation" target="_self"><sup>(v)</sup></a><br>
  21     </div>
  22     <h4>Arguments</h4>
  23     <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x<br>
  24       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; A tuple
  25       whose data is the macro expansion if the <i>variadic data</i> is
  26       <b>not</b> empty<br>
  27       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; y<br>
  28       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; A tuple
  29       whose data is the macro expansion if the <i>variadic data</i> is
  30       empty<br>
  31       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ,,,<br>
  32       &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; The <i>variadic
  33         data</i> to be checked for emptiness<br>
  34     </p>
  35     <dl>
  36     </dl>
  37     <h4>Remarks</h4>
  38     <div> When the macro invocation BOOST_PP_VARIADIC_HAS_OPT() expands
  39       to 1, then this macro exists and can be invoked, otherwise this
  40       macro does not exist and attempting to invoke it will lead to a
  41       preprocessor error that the macro can not be found. Because of
  42       this condition the header file for including this macro includes
  43       the header file for the BOOST_PP_VARIADIC_HAS_OPT macro.<br>
  44       <br>
  45       The difference between this macro and the __VA_OPT__ construct
  46       illustrates a limitation of the latter construct with a trade off
  47       of simpler syntax. The differences between the __VA_OPT__
  48       construct and this macro are:<br>
  49       <ul>
  50         <li>The __VA_OPT__ construct offers a choice as its expansion
  51           only between its input preprocessing tokens or nothing (
  52           called a "single placemarker token" ) depending on whether the
  53           implicit variadic data is empty or not. There is no way using
  54           the __VA_OPT__ construct to specify any alternative but the
  55           "single placemarker token" when the variadic data is empty
  56           whereas any preprocessing tokens can be specified when the
  57           variadic data is not empty. With the BOOST_PP_VA_OPT macro the
  58           user can specify as its expansion preprocessing tokens both
  59           when the variadic data is empty and when the variadic data is
  60           not empty.</li>
  61         <li>The __VA_OPT__ construct offers a simple syntax whereas this
  62           macro is more verbose. The BOOST_PP_VA_OPT macro's first and
  63           second parameters must be Boost PP tuples of data, in order to
  64           expand to normal or variadic data, and the third parameter
  65           must be the variadic data to check for emptiness, whereas the
  66           __VA_OPT__ construct has an implied variadic data as
  67           __VA_ARGS__ to check for emptiness and can specify its
  68           expansion directly in terms of its input.</li>
  69         <li>The __VA_OPT__ construct can only be specified in the
  70           replacement list of some macro, whereas the BOOST_PP_VA_OPT
  71           macro can be used both as an alternative to the __VA_OPT__
  72           construct in the replacement list of some macro and anywhere
  73           else a macro can be used.</li>
  74         <li>It is impossible to have a left parenthesis '(' or a right
  75           parenthesis ')' as preprocessing token data within the
  76           __VA_OPT__ construct whereas both are possible as part of the
  77           expanded data for the BOOST_PP_VA_OPT macro.<br>
  78         </li>
  79       </ul>
  80       <br>
  81       The exact BOOST_PP_VA_OPT equivalent to the construct of&nbsp;
  82       '__VA_OPT__ ( pp-tokens )' in the replacement list of a macro is
  83       'BOOST_PP_VA_OPT (( pp-tokens ),(),__VA_ARGS__)'.</div>
  84     <h4>See Also</h4>
  85     <ul>
  86       <li><a href="variadic_has_opt.html">BOOST_PP_VARIADIC_HAS_OPT</a></li>
  87     </ul>
  88     <h4>Requirements</h4>
  89     <div> <b>Header:</b> &nbsp;<a
  90         href="../headers/facilities/va_opt.html">&lt;boost/preprocessor/facilities/va_opt.hpp&gt;</a>
  91     </div>
  92     <h4>Sample Code</h4>
  93     <div>
  94       <pre>#include &lt;<a href="../headers/facilities/va_opt.html">boost/preprocessor/facilities/va_opt.hpp</a>&gt;
  95
  96 # if <a href="variadic_has_opt.html">BOOST_PP_VARIADIC_HAS_OPT</a>()
  97
  98 #define DATA
  99 #define OBJECT OBJECT2
 100 #define OBJECT2
 101 #define FUNC(x) FUNC2(x)
 102 #define FUNC2(x)
 103 #define FUNC_GEN(x,y) (1,2,3)
 104
 105 <a href="va_opt.html">BOOST_PP_VA_OPT</a>((1),(2),DATA)                      // expands to 2
 106 <a href="va_opt.html">BOOST_PP_VA_OPT</a>((3),(4),OBJECT)                    // expands to 4
 107 <a href="va_opt.html">BOOST_PP_VA_OPT</a>((5),(6),FUNC(1))                   // expands to 6
 108 <a href="va_opt.html">BOOST_PP_VA_OPT</a>((7,8),(9,10),FUNC)                 // expands to 7,8
 109 <a href="va_opt.html">BOOST_PP_VA_OPT</a>((1,2,3,4,5),(6,7,8,9,10),FUNC_GEN) // expands to 1,2,3,4,5
 110
 111 #endif
 112 </pre>
 113     </div>
 114     <hr size="1">
 115     <div style="margin-left: 0px;"> <i>© Copyright Edward Diener 2019</i>
 116     </div>
 117     <div style="margin-left: 0px;">
 118       <p><small>Distributed under the Boost Software License, Version
 119           1.0. (See accompanying file <a
 120             href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
 121           copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</small></p>
 122     </div>
 123   </body>
 124 </html>