libs/preprocessor/doc/topics/emptiness.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3   <head>
   4     <meta content="text/html; charset=windows-1252"
   5       http-equiv="content-type">
   6     <title>emptiness.html</title>
   7     <link rel="stylesheet" type="text/css" href="../styles.css">
   8     <style>
   9     u { font-weight: normal; text-decoration: none; }
  10     </style>
  11   </head>
  12   <body>
  13     <h4>Passing nothing</h4>
  14     <div> Although rarely desirable it has always been legal in C++ to
  15       pass nothing, aka no preprocessor tokens, as an argument when
  16       invoking a macro, whether the equivalent parameter be a regular
  17       parameter or a variadic one. </div>
  18     <div class="code">
  19       <pre>      #define SOME_MACRO(Parameter1,Parameter2) macro expansion using Parameter1 and Parameter2
  20       #define SOME_VARIADIC_MACRO(Parameter1,...) macro expansion using Parameter1 and __VA_ARGS__
  21
  22       SOME_MACRO(a,b) // Normal
  23       SOME_MACRO(a,)  // Legal, second argument is empty
  24       SOME_MACRO(,b)  // Legal, first argument is empty
  25       SOME_MACRO(a)   // Preprocessor error, passing the wrong number of arguments
  26
  27       SOME_VARIADIC_MACRO(a,b,c,d) // Normal
  28       SOME_VARIADIC_MACRO(a,)      // Legal, variadic argument is empty
  29       SOME_VARIADIC_MACRO(,b,c,d)  // Legal, first argument is empty
  30       SOME_VARIADIC_MACRO(a)       /* Preprocessor error in standard below C++20 level,
  31                                       but in C++20 exactly equivalent to SOME_VARIADIC_MACRO(a,) */</pre>
  32     </div>
  33     <h4>Expanding to nothing</h4>
  34     <div> Given certain arguments a macro might expand to nothing, aka
  35       no preprocessor tokens. This may happen more than in the previous
  36       case of an argument to a macro being nothing because the expansion
  37       of a macro is often used to initialize some C++ construct, and C++
  38       has some places where a part of a compile-time construct can be
  39       empty. However a macro which expands to nothing rarely occurs when
  40       that macro's expansion is used as an argument to another macro
  41       because we would again have a macro where we are passing nothing
  42       as an argument. </div>
  43     <div class="code">
  44       <pre>      #define ANOTHER_MACRO(Parameter1,Parameter2) /* expands to nothing when Parameter1 and Parameter2
  45                                                       are numbers, otherwise expands to some preprocessing
  46                                                       token, such as '1' */
  47
  48       int another_int = { ANOTHER_MACRO(x,y) }; // ANOTHER_MACRO Expands to 1
  49       int some_int = { ANOTHER_MACRO(1,2) };    // ANOTHER_MACRO Expands to nothing
  50       SOME_MACRO(ANOTHER_MACRO(x,y),z)          // Normal, ANOTHER_MACRO Expands to 1
  51       SOME_MACRO(ANOTHER_MACRO(1,2),z)          // Legal, first argument is empty as ANOTHER_MACRO Expands to nothing</pre>
  52     </div>
  53     <h4>Emptiness defined</h4>
  54     <div> Passing nothing as a macro argument or a macro expanding to
  55       nothing I term as 'emptiness', as 'nothing' is too amorphous a
  56       term which can be used in too many other contexts for my liking.
  57       In the vast majority of cases when designing a macro for use
  58       emptiness is not a part of such a design, and passing emptiness as
  59       an argument or expanding to emptiness is not anything that someone
  60       writing a macro takes into account when he explains to other
  61       programmers how a macro should be used.<br>
  62       <br>
  63       Other than the fact that macros are generally created so that some
  64       actual preprocessor data of a particular kind needs to be passed
  65       as arguments or gets generated as part of macro expansion when a
  66       macro is invoked, there is another very good reason why working
  67       with emptiness is not part of a macro's design: there has been no
  68       perfectly fail-safe way to test for emptiness during macro
  69       expansion, whether it be in creating macros using just the
  70       facilities of the C++ standard or using a 3rd party library, such
  71       as this Boost preprocessor library. When I say 'fail-safe' I mean
  72       that there has always been some argument input, no matter how
  73       small the number of potential cases, where a macro designed to
  74       test whether or not the preprocessor data passed to it as an
  75       argument when the macro is invoked is actually empty fails in some
  76       way, with the failure normally occurring as a preprocessor error.<br>
  77       <br>
  78       Of course this does not mean that the best macro designed to test
  79       for emptiness will not work correctly the vast majority of the
  80       time. It only means that there has been no guarantee that such a
  81       macro will work correctly all 100% of the time. Nonetheless there
  82       have been uses of testing for emptiness, when a macro documents
  83       what a particular argument should generally consist of, even if
  84       the test is not guaranteed to work 100% of the time if particular
  85       unexpected argument data does get passed. </div>
  86     <h4>A C++20 solution for testing for emptiness</h4>
  87     <div> The C++ standard committee recognized, in the upcoming
  88       specification for the C++20 standard, that a way of testing
  89       whether variadic data is empty or not in the expansion of a
  90       variadic macro would be very useful when designing certain types
  91       of macros. Because of this the C++20 standard added a preprocessor
  92       construct which could do this in a certain way for variadic data
  93       in the expansion of a variadic macro. The construct is called
  94       __VA_OPT__, as in '__VA_OPT__ ( prepocessing tokens )' specified
  95       in the replacement list of a variadic macro. <br>
  96       <br>
  97       The way that the __VA_OPT__ constructs works is that if the
  98       variadic arguments to the variadic macro are empty or expand to
  99       emptiness then the __VA_OPT__ construct and its enclosed
 100       preprocessing token data expands to nothing, or in C++ terms "a
 101       single placemarker preprocessing token". Otherwise the __VA_OPT__
 102       construct expands to its enclosed preprocessing tokens. A further,
 103       possibly unintended, upshot of adding the __VA_OPT__ construct to
 104       C++20 is that it is now possible to create a variadic macro which
 105       is 100% reliable in testing for emptiness whenever a compiler
 106       supports the __VA_OPT__ construct in its compilation of
 107       preprocessor code.<br>
 108       <br>
 109       For such a macro to always work which tests for emptiness the code
 110       must know when the __VA_OPT__ construct is available. It is not
 111       enough to know that a compiler is working at the C++20 level,
 112       since as all C++ programmers know an adherence to a C++ standard
 113       level never guarantees that a particular compiler supports every
 114       aspect of that level. Happily there is a way to test whether a
 115       compiler supports the __VA_OPT__ construct as long as the compiler
 116       supports variadic macros, and that way has been openly published
 117       on the Internet, although the actual macro code would not have
 118       been hard to create even if it had not publicly appeared. This
 119       library uses that code to test for __VA_OPT__ as a necessary
 120       prelude for creating a variadic macro which is 100% reliable in
 121       testing for emptiness.<br>
 122       <br>
 123       The Boost Preprocessor macro for testing whether the __VA_OPT__
 124       construct is supported during compilation is called
 125       BOOST_PP_VARIADIC_HAS_OPT, which is a function-like macro taking
 126       no parameters and returning 1 if the __VA_OPT__ construct is
 127       supported and 0 if it is not. The macro only returns 1 when
 128       variadic macros are supported, when the compiler is at the C++20
 129       level, and when the __VA_OPT__ construct can be used according to
 130       the C++20 standard. In particular the macro needs the compiler to
 131       be working at the C++20 level despite the fact that at least one
 132       major compiler supports the __VA_OPT__ construct in some of its
 133       latest releases even when the compiler is being used at a C++
 134       standard level below that of C++20. The reason this Boost
 135       preprocessor library requires the C++20 level is because that same
 136       major compiler can produce a warning, or even an error, when it
 137       even sees a macro using the __VA_OPT__ construct at a level below
 138       C++20, even though it supports it, if other compiler options
 139       requiring strict adherence to the level of the C++ standard being
 140       used are passed on the command line. So taking a conservative
 141       approach the BOOST_PP_VARIADIC_HAS_OPT macros requires compilation
 142       at the C++20 level, along with variadic macro support, along with
 143       the testing code expanding to 1, in order to specify that
 144       __VA_OPT__ is supported.<br>
 145       <br>
 146       The actual Boost Preprocessor library for testing for emptiness in
 147       C++20 mode is called BOOST_PP_CHECK_EMPTY. The macro is a variadic
 148       macro with a single variadic parameter. The macro only exists if
 149       our previous macro for testing for __VA_OPT__, called
 150       BOOST_PP_VARIADIC_HAS_OPT, expands to 1 when invoked as
 151       BOOST_PP_VARIADIC_HAS_OPT(). If BOOST_PP_VARIADIC_HAS_OPT()
 152       expands to 0 the BOOST_PP_CHECK_EMPTY macro does not exist at all
 153       in this library. The input to the BOOST_PP_CHECK_EMPTY macro can
 154       be any variadic data. If the data passed to the macro is empty, or
 155       if the data passed to the macro is not empty but when the data
 156       itself is expanded it is empty, the macro returns 1, otherwise it
 157       returns 0. The macro works 100% of the time and is completely
 158       reliable no matter what preprocessor data is passed to it. But of
 159       course it only works when compiling at the C++20 level with the
 160       __VA_OPT__ construct supported by the compiler. It solves an old
 161       problem that it has never been possible, prior to C++20, to
 162       provide a 100% reliable implementation of a macro which tests for
 163       emptiness in C++.<br>
 164       <br>
 165       Along with the valuable BOOST_PP_CHECK_EMPTY macro the Boost
 166       Preprocessor library has also added a more flexible, if slightly
 167       verbose, alternative to the __VA_OPT__ construct, which works by
 168       using the ability of BOOST_PP_CHECK_EMPTY to reliably test for
 169       emptiness. This macro is called BOOST_PP_VA_OPT and allows the
 170       programmer to specify preprocessing tokens for expansion both when
 171       the variadic data is <b>not</b> empty and when the variadic data
 172       is empty. This improves on the __VA_OPT__ construct's ability to
 173       specify preprocessing tokens for expansion only when the variadic
 174       data is not empty. Like BOOST_PP_CHECK_EMPTY, which it uses, the
 175       BOOST_PP_VA_OPT macro only exists when BOOST_PP_VARIADIC_HAS_OPT()
 176       expands to 1. You can read further about how this macro works as
 177       an alternative to the C++20 __VA_OPT__ construct in the
 178       documentation for the macro itself.<br>
 179       <br>
 180       Eventually more C++ compilers will support C++20 and the
 181       __VA_OPT__ construct and more programmers will use compilers at
 182       the C++20 level. At that point the macro BOOST_PP_CHECK_EMPTY can
 183       be used reliably for testing emptiness in preprocessor data in
 184       macro code by all those programmers. The BOOST_PP_VA_OPT macro
 185       serves as a useful example of such use. This does not mean that
 186       designing macros with emptiness in mind needs to be done, much
 187       less considered, but that the possibility of doing so with
 188       complete reliability will be there if needed by the macro
 189       programmer. Along with the __VA_OPT__ construct as mandated by the
 190       C++20 standard the BOOST_PP_CHECK_EMPTY and BOOST_PP_VA_OPT macros
 191       add three more tools in the arsenal of macro programming, which is
 192       a good thing, while programmers who wanted to ignore any dealing
 193       with emptiness in macro code can continue to do so. </div>
 194     <b>See</b> <b>Also</b><br>
 195     <ul>
 196       <li><a href="../ref/variadic_has_opt.html">BOOST_PP_VARIADIC_HAS_OPT</a></li>
 197       <li><a href="../ref/check_empty.html">BOOST_PP_CHECK_EMPTY</a></li>
 198       <li><a href="../ref/va_opt.html">BOOST_PP_VA_OPT</a><br>
 199       </li>
 200     </ul>
 201     <hr size="1">
 202     <div style="margin-left: 0px;"> <i>© Copyright Edward Diener 2019</i>
 203     </div>
 204     <div style="margin-left: 0px;">
 205       <p><small>Distributed under the Boost Software License, Version
 206           1.0. (See accompanying file <a
 207             href="../../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
 208           copy at <a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a>)</small></p>
 209     </div>
 210   </body>
 211 </html>