241 lines
12 KiB
Markdown
241 lines
12 KiB
Markdown
[cpp.replace.general]
|
||
|
||
# 15 Preprocessing directives [[cpp]](./#cpp)
|
||
|
||
## 15.7 Macro replacement [[cpp.replace]](cpp.replace#general)
|
||
|
||
### 15.7.1 General [cpp.replace.general]
|
||
|
||
[1](#1)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1443)
|
||
|
||
Two replacement lists are identical if and only if
|
||
the preprocessing tokens in both have
|
||
the same number, ordering, spelling, and whitespace separation,
|
||
where all whitespace separations are considered identical[.](#1.sentence-1)
|
||
|
||
[2](#2)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1450)
|
||
|
||
An identifier currently defined as anobject-like macro (see below) may be redefined by another#define preprocessing directive provided that the second definition is an
|
||
object-like macro definition and the two replacement lists
|
||
are identical, otherwise the program is ill-formed[.](#2.sentence-1)
|
||
|
||
Likewise, an identifier currently defined as afunction-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[.](#2.sentence-2)
|
||
|
||
[3](#3)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1468)
|
||
|
||
[*Example [1](#example-1)*:
|
||
|
||
The following sequence is valid:#define OBJ_LIKE (1-1)#define OBJ_LIKE /* whitespace */ (1-1) /* other */#define FUNC_LIKE(a) ( a )#define FUNC_LIKE( a )( /* note the whitespace */ \
|
||
a /* other stuff on this line
|
||
*/ )
|
||
|
||
But the following redefinitions are invalid:#define OBJ_LIKE (0) // different token sequence#define OBJ_LIKE (1 - 1) // different whitespace#define FUNC_LIKE(b) ( a ) // different parameter usage#define FUNC_LIKE(b) ( b ) // different parameter spelling
|
||
|
||
â *end example*]
|
||
|
||
[4](#4)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1488)
|
||
|
||
There shall be whitespace between the identifier and the replacement list
|
||
in the definition of an object-like macro[.](#4.sentence-1)
|
||
|
||
[5](#5)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1493)
|
||
|
||
If the [*identifier-list*](cpp.pre#nt:identifier-list "15.1 Preamble [cpp.pre]") 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[.](#5.sentence-1)
|
||
|
||
Otherwise, there shall be at least as many arguments in the invocation as there are
|
||
parameters in the macro definition (excluding the ...)[.](#5.sentence-2)
|
||
|
||
There
|
||
shall exist a) preprocessing token that terminates the invocation[.](#5.sentence-3)
|
||
|
||
[6](#6)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1505)
|
||
|
||
The identifiers __VA_ARGS__ and __VA_OPT__ shall occur only in the [*replacement-list*](cpp.pre#nt:replacement-list "15.1 Preamble [cpp.pre]") of a function-like macro that uses the ellipsis notation in the parameters[.](#6.sentence-1)
|
||
|
||
[7](#7)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1512)
|
||
|
||
A parameter identifier in a function-like macro
|
||
shall be uniquely declared within its scope[.](#7.sentence-1)
|
||
|
||
[8](#8)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1516)
|
||
|
||
The identifier immediately following thedefine is called the[*macro name*](#def:macro,name "15.7.1 General [cpp.replace.general]")[.](#8.sentence-1)
|
||
|
||
There is one name space for macro names[.](#8.sentence-2)
|
||
|
||
Any whitespace characters preceding or following the
|
||
replacement list of preprocessing tokens are not considered
|
||
part of the replacement list for either form of macro[.](#8.sentence-3)
|
||
|
||
[9](#9)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1527)
|
||
|
||
A translation unit shall not #define or #undef names lexically identical
|
||
to keywords,
|
||
to the identifiers listed in Table [4](lex.name#tab:lex.name.special "Table 4: Identifiers with special meaning"), or
|
||
to the [*attribute-token*](dcl.attr.grammar#nt:attribute-token "9.13.1 Attribute syntax and semantics [dcl.attr.grammar]")*s* described in [[dcl.attr]](dcl.attr "9.13 Attributes"),
|
||
except that the names likely and unlikely may be
|
||
defined as function-like macros[.](#9.sentence-1)
|
||
|
||
[10](#10)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1537)
|
||
|
||
If a# preprocessing token,
|
||
followed by an identifier,
|
||
occurs lexically
|
||
at the point at which a preprocessing directive can begin,
|
||
the identifier is not subject to macro replacement[.](#10.sentence-1)
|
||
|
||
[11](#11)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1547)
|
||
|
||
A preprocessing directive of the form
|
||
|
||
# define [*identifier*](lex.name#nt:identifier "5.11 Identifiers [lex.name]") [*replacement-list*](cpp.pre#nt:replacement-list "15.1 Preamble [cpp.pre]") [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
|
||
defines an[*object-like macro*](#def:macro,object-like "15.7.1 General [cpp.replace.general]") that
|
||
causes each subsequent instance of the macro name[125](#footnote-125 "Since, by macro-replacement time, all character-literals and string-literals are preprocessing tokens, not sequences possibly containing identifier-like subsequences (see [lex.phases], translation phases), they are never scanned for macro names or parameters.") to be replaced by the replacement list of preprocessing tokens
|
||
that constitute the remainder of the directive[.](#11.sentence-1)[126](#footnote-126 "An alternative token ([lex.digraph]) is not an identifier, even when its spelling consists entirely of letters and underscores. Therefore it is not possible to define a macro whose name is the same as that of an alternative token.")
|
||
|
||
The replacement list is then rescanned for more macro names as
|
||
specified below[.](#11.sentence-2)
|
||
|
||
[12](#12)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1574)
|
||
|
||
[*Example [2](#example-2)*:
|
||
|
||
The simplest use of this facility is to define a âmanifest constantâ,
|
||
as in#define TABSIZE 100int table[TABSIZE];
|
||
|
||
â *end example*]
|
||
|
||
[13](#13)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1584)
|
||
|
||
A preprocessing directive of the form
|
||
|
||
# define [*identifier*](lex.name#nt:identifier "5.11 Identifiers [lex.name]") [*lparen*](cpp.pre#nt:lparen "15.1 Preamble [cpp.pre]") [*identifier-list*](cpp.pre#nt:identifier-list "15.1 Preamble [cpp.pre]")opt ) [*replacement-list*](cpp.pre#nt:replacement-list "15.1 Preamble [cpp.pre]") [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
# define [*identifier*](lex.name#nt:identifier "5.11 Identifiers [lex.name]") [*lparen*](cpp.pre#nt:lparen "15.1 Preamble [cpp.pre]") ... ) [*replacement-list*](cpp.pre#nt:replacement-list "15.1 Preamble [cpp.pre]") [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
# define [*identifier*](lex.name#nt:identifier "5.11 Identifiers [lex.name]") [*lparen*](cpp.pre#nt:lparen "15.1 Preamble [cpp.pre]") [*identifier-list*](cpp.pre#nt:identifier-list "15.1 Preamble [cpp.pre]") , ... ) [*replacement-list*](cpp.pre#nt:replacement-list "15.1 Preamble [cpp.pre]") [*new-line*](cpp.pre#nt:new-line "15.1 Preamble [cpp.pre]")
|
||
|
||
defines a [*function-like macro*](#def:macro,function-like "15.7.1 General [cpp.replace.general]") with parameters, whose use is
|
||
similar syntactically to a function call[.](#13.sentence-1)
|
||
|
||
The parametersare specified by the optional list of identifiers[.](#13.sentence-2)
|
||
|
||
Each subsequent instance of the function-like macro name followed by a( as the next preprocessing token
|
||
introduces the sequence of preprocessing tokens that is replaced
|
||
by the replacement list in the definition
|
||
(an invocation of the macro)[.](#13.sentence-3)
|
||
|
||
The replaced sequence of preprocessing tokens is terminated by the matching) preprocessing token, skipping intervening matched pairs of left and
|
||
right parenthesis preprocessing tokens[.](#13.sentence-4)
|
||
|
||
Within the sequence of preprocessing tokens making up an invocation
|
||
of a function-like macro,
|
||
new-line is considered a normal whitespace character[.](#13.sentence-5)
|
||
|
||
[14](#14)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1612)
|
||
|
||
The sequence of preprocessing tokens
|
||
bounded by the outside-most matching parentheses
|
||
forms the list of arguments for the function-like macro[.](#14.sentence-1)
|
||
|
||
The individual arguments within the list
|
||
are separated by comma preprocessing tokens,
|
||
but comma preprocessing tokens between matching
|
||
inner parentheses do not separate arguments[.](#14.sentence-2)
|
||
|
||
If there are sequences of preprocessing tokens within the list of
|
||
arguments that would otherwise act as preprocessing directives,[127](#footnote-127 "A conditionally-supported-directive is a preprocessing directive regardless of whether the implementation supports it.") the program is ill-formed[.](#14.sentence-3)
|
||
|
||
[15](#15)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1628)
|
||
|
||
[*Example [3](#example-3)*:
|
||
|
||
The following defines a function-like
|
||
macro whose value is the maximum of its arguments[.](#15.sentence-1)
|
||
|
||
It has the disadvantages of evaluating one or the other of its arguments
|
||
a second time
|
||
(includingside effects)
|
||
and generating more code than a function if invoked several times[.](#15.sentence-2)
|
||
|
||
It also cannot have its address taken,
|
||
as it has none[.](#15.sentence-3)
|
||
|
||
#define max(a, b) ((a) > (b) ? (a) : (b))
|
||
|
||
The parentheses ensure that the arguments and
|
||
the resulting expression are bound properly[.](#15.sentence-4)
|
||
|
||
â *end example*]
|
||
|
||
[16](#16)
|
||
|
||
[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1649)
|
||
|
||
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*](#def:variable_arguments "15.7.1 General [cpp.replace.general]")[.](#16.sentence-1)
|
||
|
||
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...)[.](#16.sentence-2)
|
||
|
||
[125)](#footnote-125)[125)](#footnoteref-125)
|
||
|
||
Since, by macro-replacement time,
|
||
all [*character-literal*](lex.ccon#nt:character-literal "5.13.3 Character literals [lex.ccon]")*s* and [*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]")*s* are preprocessing tokens,
|
||
not sequences possibly containing identifier-like subsequences
|
||
(see [[lex.phases]](lex.phases "5.2 Phases of translation"), translation phases),
|
||
they are never scanned for macro names or parameters[.](#footnote-125.sentence-1)
|
||
|
||
[126)](#footnote-126)[126)](#footnoteref-126)
|
||
|
||
An alternative token ([[lex.digraph]](lex.digraph "5.9 Alternative tokens")) is not an identifier,
|
||
even when its spelling consists entirely of letters and underscores[.](#footnote-126.sentence-1)
|
||
|
||
Therefore it is not possible to define a macro
|
||
whose name is the same as that of an alternative token[.](#footnote-126.sentence-2)
|
||
|
||
[127)](#footnote-127)[127)](#footnoteref-127)
|
||
|
||
A [*conditionally-supported-directive*](cpp.pre#nt:conditionally-supported-directive "15.1 Preamble [cpp.pre]") is a preprocessing directive regardless of whether the implementation supports it[.](#footnote-127.sentence-1)
|