[cpp.replace.general] (original) (raw)

15 Preprocessing directives [cpp]

15.7 Macro replacement [cpp.replace]

15.7.1 General [cpp.replace.general]

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.

An identifier currently defined as anobject-like macro (see below) may be redefined by another#definepreprocessing 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.

Likewise, an identifier currently defined as afunction-like macro (see below) may be redefined by another#definepreprocessing 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:#define OBJ_LIKE (1-1) #define OBJ_LIKE (1-1) #define FUNC_LIKE(a) ( a ) #define FUNC_LIKE( a )( \ a )

But the following redefinitions are invalid:#define OBJ_LIKE (0) #define OBJ_LIKE (1 - 1) #define FUNC_LIKE(b) ( a ) #define FUNC_LIKE(b) ( b )

— _end example_]

There shall be whitespace 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-listof 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 thedefineis called themacro name.

There is one name space for macro names.

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.

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.

A preprocessing directive of the form

defines anobject-like macro that causes each subsequent instance of the macro name125to be replaced by the replacement list of preprocessing tokens that constitute the remainder of the directive.126

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#define TABSIZE 100 int table[TABSIZE];

— _end example_]

A preprocessing directive of the form

defines a function-like macrowith parameters, whose use is similar syntactically to a function call.

The parametersare specified by the optional list of identifiers.

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).

The replaced sequence of preprocessing tokens is terminated by the matching)preprocessing token, skipping intervening matched pairs of left and right parenthesis preprocessing tokens.

Within the sequence of preprocessing tokens making up an invocation of a function-like macro, new-line is considered a normal whitespace character.

The sequence of preprocessing tokens bounded by the outside-most matching parentheses forms the list of arguments for the function-like 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,127the 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 (includingside effects) and generating more code than a function if invoked several times.

It also cannot have its address taken, as it has none.

#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...).