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> 212