cpp/preprocessor/replace

The preprocessor supports text macro replacement. Function-like text macro replacement is also supported.

directives
The directives define the  as macro, that is instruct the compiler to replace most successive occurrences of  with, which will be additionally processed. Exceptions arise from the rules of. If the identifier is already defined as any type of macro, the program is ill-formed unless the definitions are identical.

Object-like macros
Object-like macros replace every occurrence of defined with. Version (1) of the directive behaves exactly like that.

Function-like macros
Function-like macros replace each occurrence of defined with, additionally taking a number of arguments, which then replace corresponding occurrences of any of the  in the.

The syntax of a function-like macro invocation is similar to the syntax of a function call: each instance of the macro name followed by a as the next preprocessing token introduces the sequence of tokens that is replaced by the. The sequence is terminated by the matching token, skipping intervening matched pairs of left and right parentheses.

For version (2), the number of arguments must be the same as the number of parameters in macro definition. For versions (3,4), the number of arguments must not be less than the number of parameters ( counting ). Otherwise the program is ill-formed. If the identifier is not in functional-notation, i.e. does not have parentheses after itself, it is not replaced at all.

Version (2) of the directive defines a simple function-like macro.

Version (3) of the directive defines a function-like macro with variable number of arguments. The additional arguments (called variable arguments) can be accessed using identifier, which is then replaced with arguments, supplied with the identifier to be replaced.

Version (4) of the directive defines a function-like macro with variable number of arguments, but no regular arguments. The arguments (called variable arguments) can be accessed only with identifier, which is then replaced with arguments, supplied with the identifier to be replaced.

Note: if an argument of a function-like macro includes commas that are not protected by matched pairs of left and right parentheses (most commonly found in template argument lists, as in or ), the comma is interpreted as macro argument separator, causing a compilation failure due to argument count mismatch.

Scanning and Replacement

 * Scanning keeps track of macros they replaced. If scan finds text matching such macro, it marks it "to be ignored" (all scans will ignore it). This prevents recursion.
 * If scanning found function-like macro, arguments are scanned before put inside . Except # and ## operators take argument without scan.
 * After macro was replaced, result text is scanned.

Note, it is possible to define pseudo recursive macro:

Reserved macro names
A translation unit that includes a standard library header may not or  names declared in any standard library header.

A translation unit that uses any part of the standard library is not allowed to or  names lexically identical to:
 * keywords

Otherwise, the behavior is undefined.

and operators
In function-like macros, a operator before an identifier in the  runs the identifier through parameter replacement and encloses the result in quotes, effectively creating a string literal. In addition, the preprocessor adds backslashes to escape the quotes surrounding embedded string literals, if any, and doubles the backslashes within the string as necessary. All leading and trailing whitespace is removed, and any sequence of whitespace in the middle of the text (but not inside embedded string literals) is collapsed to a single space. This operation is called "stringification". If the result of stringification is not a valid string literal, the behavior is undefined.

A operator between any two successive identifiers in the  runs parameter replacement on the two identifiers (which are not macro-expanded first) and then concatenates the result. This operation is called "concatenation" or "token pasting". Only tokens that form a valid token together may be pasted: identifiers that form a longer identifier, digits that form a number, or operators and  that form a. A comment cannot be created by pasting and  because comments are removed from text before macro substitution is considered. If the result of concatenation is not a valid token, the behavior is undefined.

Note: some compilers offer an extension that allows to appear after a comma and before, in which case the  does nothing when the variable arguments are present, but removes the comma when the variable arguments are not present: this makes it possible to define macros such as.

directive
The directive undefines the, that is cancels previous definition of the  by  directive. If the identifier does not have associated macro, the directive is ignored.

Predefined macros
The following macro names are predefined in every translation unit:

The following additional macro names may be predefined by the implementations:

The values of these macros (except for and ) remain constant throughout the translation unit. Attempts to redefine or undefine these macros result in undefined behavior.

{{rrev|since=c++20|

Language feature-testing macros
The standard defines a set of preprocessor macros corresponding to C++ language features introduced in C++11 or later. They are intended as a simple and portable way to detect the presence of said features.

See Feature testing for details. }}