[cpp.replace] - C++17 → C++20

Files changed (1) hide show

tmp/tmpfeov8fvl/{from.md → to.md} +286 -203

tmp/tmpfeov8fvl/{from.md → to.md} RENAMED Viewed

@@ -12,24 +12,48 @@ Likewise, an identifier currently defined as a function-like macro (see
 below) may be redefined by another `#define` preprocessing directive
 provided that the second definition is a function-like macro definition
 that has the same number and spelling of parameters, and the two
 replacement lists are identical, otherwise the program is ill-formed.
 There shall be white-space between the identifier and the replacement
 list in the definition of an object-like macro.
 If the *identifier-list* in the macro definition does not end with an
 ellipsis, the number of arguments (including those arguments consisting
 of no preprocessing tokens) in an invocation of a function-like macro
 shall equal the number of parameters in the macro definition. Otherwise,
-there shall be more arguments in the invocation than there are
 parameters in the macro definition (excluding the `...`). There shall
 exist a `)` preprocessing token that terminates the invocation.
-The identifier `__VA_ARGS__` shall occur only in the *replacement-list*
-of a function-like macro that uses the ellipsis notation in the
-parameters.
 A parameter identifier in a function-like macro shall be uniquely
 declared within its scope.
 The identifier immediately following the `define` is called the *macro
@@ -52,10 +76,22 @@ defines an *object-like macro* that causes each subsequent instance of
 the macro name[^5] to be replaced by the replacement list of
 preprocessing tokens that constitute the remainder of the directive.[^6]
 The replacement list is then rescanned for more macro names as specified
 below.
 A preprocessing directive of the form
 ``` bnf
 '# define' identifier lparen identifier-listₒₚₜ ')' replacement-list new-line
 '# define' identifier lparen '...' ')' replacement-list new-line
@@ -82,56 +118,184 @@ macro. The individual arguments within the list are separated by comma
 preprocessing tokens, but comma preprocessing tokens between matching
 inner parentheses do not separate arguments. If there are sequences of
 preprocessing tokens within the list of arguments that would otherwise
 act as preprocessing directives,[^7] the behavior is undefined.
 If there is a `...` immediately preceding the `)` in the function-like
-macro definition, then the trailing arguments, including any separating
-comma preprocessing tokens, are merged to form a single item: the
-*variable arguments*. The number of arguments so combined is such that,
-following merger, the number of arguments is one more than the number of
-parameters in the macro definition (excluding the `...`).
 ### Argument substitution <a id="cpp.subst">[[cpp.subst]]</a>
 After the arguments for the invocation of a function-like macro have
-been identified, argument substitution takes place. A parameter in the
-replacement list, unless preceded by a `#` or `##` preprocessing token
-or followed by a `##` preprocessing token (see below), is replaced by
-the corresponding argument after all macros contained therein have been
-expanded. Before being substituted, each argument’s preprocessing tokens
-are completely macro replaced as if they formed the rest of the
-preprocessing file; no other preprocessing tokens are available.
 An identifier `__VA_ARGS__` that occurs in the replacement list shall be
 treated as if it were a parameter, and the variable arguments shall form
 the preprocessing tokens used to replace it.
 ### The `#` operator <a id="cpp.stringize">[[cpp.stringize]]</a>
 Each `#` preprocessing token in the replacement list for a function-like
 macro shall be followed by a parameter as the next preprocessing token
 in the replacement list.
 A *character string literal* is a *string-literal* with no prefix. If,
 in the replacement list, a parameter is immediately preceded by a `#`
 preprocessing token, both are replaced by a single character string
 literal preprocessing token that contains the spelling of the
-preprocessing token sequence for the corresponding argument. Each
-occurrence of white space between the argument’s preprocessing tokens
-becomes a single space character in the character string literal. White
-space before the first preprocessing token and after the last
-preprocessing token comprising the argument is deleted. Otherwise, the
-original spelling of each preprocessing token in the argument is
-retained in the character string literal, except for special handling
-for producing the spelling of string literals and character literals: a
-`\` character is inserted before each `"` and `\` character of a
-character literal or string literal (including the delimiting `"`
-characters). If the replacement that results is not a valid character
-string literal, the behavior is undefined. The character string literal
-corresponding to an empty argument is `""`. The order of evaluation of
-`#` and `##` operators is unspecified.
 ### The `##` operator <a id="cpp.concat">[[cpp.concat]]</a>
 A `##` preprocessing token shall not occur at the beginning or at the
 end of a replacement list for either form of macro definition.
@@ -156,10 +320,58 @@ is not a valid preprocessing token, the behavior is undefined. The
 resulting token is available for further macro replacement. The order of
 evaluation of `##` operators is unspecified.
 [*Example 1*:
 In the following fragment:
 ``` cpp
 #define hash_hash # ## #
 #define mkstr(a) # a
@@ -182,83 +394,41 @@ In other words, expanding `hash_hash` produces a new token, consisting
 of two adjacent sharp signs, but this new token is not the `##`
 operator.
 — *end example*]
 ### Rescanning and further replacement <a id="cpp.rescan">[[cpp.rescan]]</a>
 After all parameters in the replacement list have been substituted and
 `#` and `##` processing has taken place, all placemarker preprocessing
 tokens are removed. Then the resulting preprocessing token sequence is
 rescanned, along with all subsequent preprocessing tokens of the source
 file, for more macro names to replace.
-If the name of the macro being replaced is found during this scan of the
-replacement list (not including the rest of the source file’s
-preprocessing tokens), it is not replaced. Furthermore, if any nested
-replacements encounter the name of the macro being replaced, it is not
-replaced. These nonreplaced macro name preprocessing tokens are no
-longer available for further replacement even if they are later
-(re)examined in contexts in which that macro name preprocessing token
-would otherwise have been replaced.
-The resulting completely macro-replaced preprocessing token sequence is
-not processed as a preprocessing directive even if it resembles one, but
-all pragma unary operator expressions within it are then processed as
-specified in  [[cpp.pragma.op]] below.
-### Scope of macro definitions <a id="cpp.scope">[[cpp.scope]]</a>
-A macro definition lasts (independent of block structure) until a
-corresponding `#undef` directive is encountered or (if none is
-encountered) until the end of the translation unit. Macro definitions
-have no significance after translation phase 4.
-A preprocessing directive of the form
-``` bnf
-'# undef' identifier new-line
-```
-causes the specified identifier no longer to be defined as a macro name.
-It is ignored if the specified identifier is not currently defined as a
-macro name.
 [*Example 1*:
-The simplest use of this facility is to define a “manifest constant”, as
-in
-``` cpp
-#define TABSIZE 100
-int table[TABSIZE];
-```
-— *end example*]
-[*Example 2*:
-The following defines a function-like macro whose value is the maximum
-of its arguments. It has the advantages of working for any compatible
-types of the arguments and of generating in-line code without the
-overhead of function calling. It has the disadvantages of evaluating one
-or the other of its arguments a second time (including side effects) and
-generating more code than a function if invoked several times. It also
-cannot have its address taken, as it has none.
-``` cpp
-#define max(a, b) ((a) > (b) ? (a) : (b))
-```
-The parentheses ensure that the arguments and the resulting expression
-are bound properly.
-— *end example*]
-[*Example 3*:
-To illustrate the rules for redefinition and reexamination, the sequence
 ``` cpp
 #define x       3
 #define f(a)    f(x * (a))
 #undef  x
@@ -290,123 +460,36 @@ int i[] = { 1, 23, 4, 5, };
 char c[2][6] = { "hello", "" };
 ```
 — *end example*]
-[*Example 4*:
-To illustrate the rules for creating character string literals and
-concatenating tokens, the sequence
-``` cpp
-#define str(s)      # s
-#define xstr(s)     str(s)
-#define debug(s, t) printf("x" # s "= %d, x" # t "= %s", \
-               x ## s, x ## t)
-#define INCFILE(n)  vers ## n
-#define glue(a, b)  a ## b
-#define xglue(a, b) glue(a, b)
-#define HIGHLOW     "hello"
-#define LOW         LOW ", world"
-debug(1, 2);
-fputs(str(strncmp("abc\0d", "abc", '\4')        // this goes away
-    == 0) str(: \@n), s);
-#include xstr(INCFILE(2).h)
-glue(HIGH, LOW);
-xglue(HIGH, LOW)
-```
-results in
-``` cpp
-printf("x" "1" "= %d, x" "2" "= %s", x1, x2);
-fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0" ": \@n", s);
-#include "vers2.h"      (after macro replacement, before file access)
-"hello";
-"hello" ", world"
-```
-or, after concatenation of the character string literals,
-``` cpp
-printf("x1= %d, x2= %s", x1, x2);
-fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0: \@n", s);
-#include "vers2.h"      (after macro replacement, before file access)
-"hello";
-"hello, world"
-```
-Space around the `#` and `##` tokens in the macro definition is
-optional.
-— *end example*]
-[*Example 5*:
-To illustrate the rules for placemarker preprocessing tokens, the
-sequence
-``` cpp
-#define t(x,y,z) x ## y ## z
-int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),
-  t(10,,), t(,11,), t(,,12), t(,,) };
-```
-results in
-``` cpp
-int j[] = { 123, 45, 67, 89,
-  10, 11, 12, };
-```
-— *end example*]
-[*Example 6*:
-To demonstrate the redefinition rules, the following sequence is valid.
-``` cpp
-#define OBJ_LIKE      (1-1)
-#define OBJ_LIKE      /* white space */ (1-1) /* other */
-#define FUNC_LIKE(a)   ( a )
-#define FUNC_LIKE( a )(     /* note the white space */ \
-                a /* other stuff on this line
-                  */ )
-```
-But the following redefinitions are invalid:
-``` cpp
-#define OBJ_LIKE    (0)         // different token sequence
-#define OBJ_LIKE    (1 - 1)     // different white space
-#define FUNC_LIKE(b) ( a )      // different parameter usage
-#define FUNC_LIKE(b) ( b )      // different parameter spelling
-```
-— *end example*]
-[*Example 7*:
-Finally, to show the variable argument list macro facilities:
-``` cpp
-#define debug(...) fprintf(stderr, __VA_ARGS__)
-#define showlist(...) puts(#__VA_ARGS__)
-#define report(test, ...) ((test) ? puts(#test) : printf(__VA_ARGS__))
-debug("Flag");
-debug("X = %d\n", x);
-showlist(The first, second, and third items.);
-report(x>y, "x is %d but y is %d", x, y);
-```
-results in
-``` cpp
-fprintf(stderr, "Flag");
-fprintf(stderr, "X = %d\n", x);
-puts("The first, second, and third items.");
-((x>y) ? puts("x>y") : printf("x is %d but y is %d", x, y));
 ```
-— *end example*]

 below) may be redefined by another `#define` preprocessing directive
 provided that the second definition is a function-like macro definition
 that has the same number and spelling of parameters, and the two
 replacement lists are identical, otherwise the program is ill-formed.
+[*Example 1*:
+The following sequence is valid:
+``` cpp
+#define OBJ_LIKE      (1-1)
+#define OBJ_LIKE      /* white space */ (1-1) /* other */
+#define FUNC_LIKE(a)   ( a )
+#define FUNC_LIKE( a )(     /* note the white space */ \
+                a /* other stuff on this line
+                  */ )
+```
+But the following redefinitions are invalid:
+``` cpp
+#define OBJ_LIKE    (0)         // different token sequence
+#define OBJ_LIKE    (1 - 1)     // different white space
+#define FUNC_LIKE(b) ( a )      // different parameter usage
+#define FUNC_LIKE(b) ( b )      // different parameter spelling
+```
+— *end example*]
 There shall be white-space between the identifier and the replacement
 list in the definition of an object-like macro.
 If the *identifier-list* in the macro definition does not end with an
 ellipsis, the number of arguments (including those arguments consisting
 of no preprocessing tokens) in an invocation of a function-like macro
 shall equal the number of parameters in the macro definition. Otherwise,
+there shall be at least as many arguments in the invocation as there are
 parameters in the macro definition (excluding the `...`). There shall
 exist a `)` preprocessing token that terminates the invocation.
+The identifiers `__VA_ARGS__` and `__VA_OPT__` shall occur only in the
+*replacement-list* of a function-like macro that uses the ellipsis
+notation in the parameters.
 A parameter identifier in a function-like macro shall be uniquely
 declared within its scope.
 The identifier immediately following the `define` is called the *macro
 the macro name[^5] to be replaced by the replacement list of
 preprocessing tokens that constitute the remainder of the directive.[^6]
 The replacement list is then rescanned for more macro names as specified
 below.
+[*Example 2*:
+The simplest use of this facility is to define a “manifest constant”, as
+in
+``` cpp
+#define TABSIZE 100
+int table[TABSIZE];
+```
+— *end example*]
 A preprocessing directive of the form
 ``` bnf
 '# define' identifier lparen identifier-listₒₚₜ ')' replacement-list new-line
 '# define' identifier lparen '...' ')' replacement-list new-line
 preprocessing tokens, but comma preprocessing tokens between matching
 inner parentheses do not separate arguments. If there are sequences of
 preprocessing tokens within the list of arguments that would otherwise
 act as preprocessing directives,[^7] the behavior is undefined.
+[*Example 3*:
+The following defines a function-like macro whose value is the maximum
+of its arguments. It has the disadvantages of evaluating one or the
+other of its arguments a second time (including side effects) and
+generating more code than a function if invoked several times. It also
+cannot have its address taken, as it has none.
+``` cpp
+#define max(a, b) ((a) > (b) ? (a) : (b))
+```
+The parentheses ensure that the arguments and the resulting expression
+are bound properly.
+— *end example*]
 If there is a `...` immediately preceding the `)` in the function-like
+macro definition, then the trailing arguments (if any), including any
+separating comma preprocessing tokens, are merged to form a single item:
+the *variable arguments*. The number of arguments so combined is such
+that, following merger, the number of arguments is either equal to or
+one more than the number of parameters in the macro definition
+(excluding the `...`).
 ### Argument substitution <a id="cpp.subst">[[cpp.subst]]</a>
+``` bnf
+va-opt-replacement:
+    '__VA_OPT__ (' pp-tokensₒₚₜ ')'
+```
 After the arguments for the invocation of a function-like macro have
+been identified, argument substitution takes place. For each parameter
+in the replacement list that is neither preceded by a `#` or `##`
+preprocessing token nor followed by a `##` preprocessing token, the
+preprocessing tokens naming the parameter are replaced by a token
+sequence determined as follows:
+- If the parameter is of the form *va-opt-replacement*, the replacement
+  preprocessing tokens are the preprocessing token sequence for the
+  corresponding argument, as specified below.
+- Otherwise, the replacement preprocessing tokens are the preprocessing
+  tokens of corresponding argument after all macros contained therein
+  have been expanded. The argument’s preprocessing tokens are completely
+  macro replaced before being substituted as if they formed the rest of
+  the preprocessing file with no other preprocessing tokens being
+  available.
+[*Example 1*:
+``` cpp
+#define LPAREN() (
+#define G(Q) 42
+#define F(R, X, ...)  __VA_OPT__(G R X) )
+int x = F(LPAREN(), 0, <:-);    // replaced by int x = 42;
+```
+— *end example*]
 An identifier `__VA_ARGS__` that occurs in the replacement list shall be
 treated as if it were a parameter, and the variable arguments shall form
 the preprocessing tokens used to replace it.
+[*Example 2*:
+``` cpp
+#define debug(...) fprintf(stderr, __VA_ARGS__)
+#define showlist(...) puts(#__VA_ARGS__)
+#define report(test, ...) ((test) ? puts(#test) : printf(__VA_ARGS__))
+debug("Flag");
+debug("X = %d\n", x);
+showlist(The first, second, and third items.);
+report(x>y, "x is %d but y is %d", x, y);
+```
+results in
+``` cpp
+fprintf(stderr, "Flag");
+fprintf(stderr, "X = %d\n", x);
+puts("The first, second, and third items.");
+((x>y) ? puts("x>y") : printf("x is %d but y is %d", x, y));
+```
+— *end example*]
+The identifier `__VA_OPT__` shall always occur as part of the
+preprocessing token sequence *va-opt-replacement*; its closing `)` is
+determined by skipping intervening pairs of matching left and right
+parentheses in its *pp-tokens*. The *pp-tokens* of a
+*va-opt-replacement* shall not contain `__VA_OPT__`. If the *pp-tokens*
+would be ill-formed as the replacement list of the current function-like
+macro, the program is ill-formed. A *va-opt-replacement* is treated as
+if it were a parameter, and the preprocessing token sequence for the
+corresponding argument is defined as follows. If the substitution of
+`__VA_ARGS__` as neither an operand of `#` nor `##` consists of no
+preprocessing tokens, the argument consists of a single placemarker
+preprocessing token ([[cpp.concat]], [[cpp.rescan]]). Otherwise, the
+argument consists of the results of the expansion of the contained
+*pp-tokens* as the replacement list of the current function-like macro
+before removal of placemarker tokens, rescanning, and further
+replacement.
+[*Note 1*: The placemarker tokens are removed before stringization
+[[cpp.stringize]], and can be removed by rescanning and further
+replacement [[cpp.rescan]]. — *end note*]
+[*Example 3*:
+``` cpp
+#define F(...)           f(0 __VA_OPT__(,) __VA_ARGS__)
+#define G(X, ...)        f(0, X __VA_OPT__(,) __VA_ARGS__)
+#define SDEF(sname, ...) S sname __VA_OPT__(= { __VA_ARGS__ })
+#define EMP
+F(a, b, c)          // replaced by f(0, a, b, c)
+F()                 // replaced by f(0)
+F(EMP)              // replaced by f(0)
+G(a, b, c)          // replaced by f(0, a, b, c)
+G(a, )              // replaced by f(0, a)
+G(a)                // replaced by f(0, a)
+SDEF(foo);          // replaced by S foo;
+SDEF(bar, 1, 2);    // replaced by S bar = { 1, 2 }
+#define H1(X, ...) X __VA_OPT__(##) __VA_ARGS__ // error: ## may not appear at
+                                                // the beginning of a replacement list[cpp.concat]
+#define H2(X, Y, ...) __VA_OPT__(X ## Y,) __VA_ARGS__
+H2(a, b, c, d)      // replaced by ab, c, d
+#define H3(X, ...) #__VA_OPT__(X##X X##X)
+H3(, 0)             // replaced by ""
+#define H4(X, ...) __VA_OPT__(a X ## X) ## b
+H4(, 1)             // replaced by a b
+#define H5A(...) __VA_OPT__()/**/__VA_OPT__()
+#define H5B(X) a ## X ## b
+#define H5C(X) H5B(X)
+H5C(H5A())          // replaced by ab
+```
+— *end example*]
 ### The `#` operator <a id="cpp.stringize">[[cpp.stringize]]</a>
 Each `#` preprocessing token in the replacement list for a function-like
 macro shall be followed by a parameter as the next preprocessing token
 in the replacement list.
 A *character string literal* is a *string-literal* with no prefix. If,
 in the replacement list, a parameter is immediately preceded by a `#`
 preprocessing token, both are replaced by a single character string
 literal preprocessing token that contains the spelling of the
+preprocessing token sequence for the corresponding argument (excluding
+placemarker tokens). Let the *stringizing argument* be the preprocessing
+token sequence for the corresponding argument with placemarker tokens
+removed. Each occurrence of white space between the stringizing
+argument’s preprocessing tokens becomes a single space character in the
+character string literal. White space before the first preprocessing
+token and after the last preprocessing token comprising the stringizing
+argument is deleted. Otherwise, the original spelling of each
+preprocessing token in the stringizing argument is retained in the
+character string literal, except for special handling for producing the
+spelling of *string-literal*s and *character-literal*s: a `\` character
+is inserted before each `"` and `\` character of a *character-literal*
+or *string-literal* (including the delimiting `"` characters). If the
+replacement that results is not a valid character string literal, the
+behavior is undefined. The character string literal corresponding to an
+empty stringizing argument is `""`. The order of evaluation of `#` and
+`##` operators is unspecified.
 ### The `##` operator <a id="cpp.concat">[[cpp.concat]]</a>
 A `##` preprocessing token shall not occur at the beginning or at the
 end of a replacement list for either form of macro definition.
 resulting token is available for further macro replacement. The order of
 evaluation of `##` operators is unspecified.
 [*Example 1*:
+The sequence
+``` cpp
+#define str(s)      # s
+#define xstr(s)     str(s)
+#define debug(s, t) printf("x" # s "= %d, x" # t "= %s", \
+               x ## s, x ## t)
+#define INCFILE(n)  vers ## n
+#define glue(a, b)  a ## b
+#define xglue(a, b) glue(a, b)
+#define HIGHLOW     "hello"
+#define LOW         LOW ", world"
+debug(1, 2);
+fputs(str(strncmp("abc\0d", "abc", '\4')        // this goes away
+    == 0) str(: \@n), s);
+#include xstr(INCFILE(2).h)
+glue(HIGH, LOW);
+xglue(HIGH, LOW)
+```
+results in
+``` cpp
+printf("x" "1" "= %d, x" "2" "= %s", x1, x2);
+fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0" ": \@n", s);
+#include "vers2.h"      (after macro replacement, before file access)
+"hello";
+"hello" ", world"
+```
+or, after concatenation of the character string literals,
+``` cpp
+printf("x1= %d, x2= %s", x1, x2);
+fputs("strncmp(\"abc\\0d\", \"abc\", '\\4') == 0: \@n", s);
+#include "vers2.h"      (after macro replacement, before file access)
+"hello";
+"hello, world"
+```
+Space around the `#` and `##` tokens in the macro definition is
+optional.
+— *end example*]
+[*Example 2*:
 In the following fragment:
 ``` cpp
 #define hash_hash # ## #
 #define mkstr(a) # a
 of two adjacent sharp signs, but this new token is not the `##`
 operator.
 — *end example*]
+[*Example 3*:
+To illustrate the rules for placemarker preprocessing tokens, the
+sequence
+``` cpp
+#define t(x,y,z) x ## y ## z
+int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),
+  t(10,,), t(,11,), t(,,12), t(,,) };
+```
+results in
+``` cpp
+int j[] = { 123, 45, 67, 89,
+  10, 11, 12, };
+```
+— *end example*]
 ### Rescanning and further replacement <a id="cpp.rescan">[[cpp.rescan]]</a>
 After all parameters in the replacement list have been substituted and
 `#` and `##` processing has taken place, all placemarker preprocessing
 tokens are removed. Then the resulting preprocessing token sequence is
 rescanned, along with all subsequent preprocessing tokens of the source
 file, for more macro names to replace.
 [*Example 1*:
+The sequence
 ``` cpp
 #define x       3
 #define f(a)    f(x * (a))
 #undef  x
 char c[2][6] = { "hello", "" };
 ```
 — *end example*]
+If the name of the macro being replaced is found during this scan of the
+replacement list (not including the rest of the source file’s
+preprocessing tokens), it is not replaced. Furthermore, if any nested
+replacements encounter the name of the macro being replaced, it is not
+replaced. These nonreplaced macro name preprocessing tokens are no
+longer available for further replacement even if they are later
+(re)examined in contexts in which that macro name preprocessing token
+would otherwise have been replaced.
+The resulting completely macro-replaced preprocessing token sequence is
+not processed as a preprocessing directive even if it resembles one, but
+all pragma unary operator expressions within it are then processed as
+specified in  [[cpp.pragma.op]] below.
+### Scope of macro definitions <a id="cpp.scope">[[cpp.scope]]</a>
+A macro definition lasts (independent of block structure) until a
+corresponding `#undef` directive is encountered or (if none is
+encountered) until the end of the translation unit. Macro definitions
+have no significance after translation phase 4.
+A preprocessing directive of the form
+``` bnf
+'# undef' identifier new-line
 ```
+causes the specified identifier no longer to be defined as a macro name.
+It is ignored if the specified identifier is not currently defined as a
+macro name.

Diff to HTML by rtfpessoa