Replacing text macros

From cppreference.com
C++ language
General topics
Flow control
Conditional execution statements
Iteration statements (loops)
Jump statements
Functions
Function declaration
Lambda function declaration
inline specifier
Exception specifications (deprecated)
noexcept specifier (C++11)
Exceptions
Namespaces
Types
Specifiers
decltype (C++11)
auto (C++11)
alignas (C++11)
Storage duration specifiers
Initialization
Expressions
Alternative representations
Literals
Boolean - Integer - Floating-point
Character - String - nullptr (C++11)
User-defined (C++11)
Utilities
Attributes (C++11)
Types
typedef declaration
Type alias declaration (C++11)
Casts
Implicit conversions - Explicit conversions
static_cast - dynamic_cast
const_cast - reinterpret_cast
Memory allocation
Classes
Class-specific function properties
Special member functions
Templates
Miscellaneous

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

Syntax

#define identifier replacement-list(optional) (1)
#define identifier( parameters ) replacement-list(optional) (2)
#define identifier( parameters, ... ) replacement-list(optional) (3) (since C++11)
#define identifier( ... ) replacement-list(optional) (4) (since C++11)
#undef identifier (5)

Explanation

#define directives

The #define directives define the identifier as macro, that is instruct the compiler to replace all successive occurrences of identifier with replacement-list, which can be optionally additionally processed. 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 identifier with replacement-list. Version (1) of the #define directive behaves exactly like that.

Function-like macros

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

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 replacement-list. 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 be more than (until C++20)at least as many as (since C++20) the number of parameters (not 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 #define directive defines a simple function-like macro.

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

Version (4) of the #define 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 __VA_ARGS__ identifier, which is then replaced with arguments, supplied with identifier to be replaced.

For versions (3,4), replacement-list may contain the token sequence __VA_OPT__ ( content ), which is replaced by content if __VA_ARGS__ is non-empty, and expands to nothing otherwise.

#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__ })
F(a, b, c) // replaced by f(0, a, b, c)
F()        // 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 };
(since C++20)

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 assert(std::is_same_v<int, int>); or BOOST_FOREACH(std::pair<int,int> p, m)), the comma is interpreted as macro argument separator, causing a compilation failure due to argument count mismatch.

# and ## operators

In function-like macros, a # operator before an identifier in the replacement-list 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.

When # appears before __VA_ARGS__, the entire expanded __VA_ARGS__ is enclosed in quotes:

#define showlist(...) puts(#__VA_ARGS__)
showlist();            // expands to puts("")
showlist(1, "x", int); // expands to puts("1, \"x\", int")
(since C++11)

A ## operator between any two successive identifiers in the replacement-list 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 __VA_ARGS__, 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 fprintf (stderr, format, ##__VA_ARGS__)

#undef directive

The #undef directive undefines the identifier, that is cancels previous definition of the identifier by #define 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.

__cplusplus
denotes the version of C++ standard that is being used, expands to value 199711L(until C++11), 201103L(C++11), 201402L(C++14), or 201703L(C++17)
(macro constant)
__STDC_HOSTED__
(C++11)
expands to the integer constant 1 if the implementation is hosted (runs under an OS), 0 if freestanding (runs without an OS)
(macro constant)
__FILE__
expands to the name of the current file, as a character string literal, can be changed by the #line directive
(macro constant)
__LINE__
expands to the source file line number, an integer constant, can be changed by the #line directive
(macro constant)
__DATE__
expands to the date of translation, a character string literal of the form "Mmm dd yyyy". The first character of "dd" is a space if the day of the month is less than 10. The name of the month is as if generated by std::asctime()
(macro constant)
__TIME__
expands to the time of translation, a character string literal of the form "hh:mm:ss"
(macro constant)
__STDCPP_DEFAULT_NEW_ALIGNMENT__
(C++17)
expands to an std::size_t literal whose value is the alignment guaranteed by a call to alignment-unaware operator new (larger alignments will be passed to alignment-aware overload, such as operator new(std::size_t, std::align_val_t)
(macro constant)

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

__STDC__
implementation-defined value, if present, typically used to indicate C conformance
(macro constant)
__STDC_VERSION__
(C++11)
implementation-defined value, if present
(macro constant)
__STDC_ISO_10646__
(C++11)
expands to an integer constant of the form yyyymmL, if wchar_t uses Unicode, the date indicates the latest revision of Unicode supported
(macro constant)
__STDC_MB_MIGHT_NEQ_WC__
(C++11)
expands to 1 if 'x' == L'x' might be false for a member of the basic character set, such as on EBCDIC-based systems that use Unicode for wchar_t.
(macro constant)
__STDCPP_STRICT_POINTER_SAFETY__
(C++11)
expands to 1 if the implementation has strict std::pointer_safety
(macro constant)
__STDCPP_THREADS__
(C++11)
expands to 1 if the program can have more than one thread of execution
(macro constant)

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

Note: in the scope of every function body, there is a special function-local predefined variable named __func__(since C++11), defined as a static character array holding the name of the function in implementation-defined format. It is not a preprocessor macro, but it is used together with __FILE__ and __LINE__, e.g. by assert.

Language feature-testing macros

The following macros are predefined in every translation unit.

__cpp_aggregate_bases
expands to the integer literal 201603L
(macro constant)
__cpp_aggregate_nsdmi
expands to the integer literal 201304L
(macro constant)
__cpp_alias_templates
expands to the integer literal 200704L
(macro constant)
__cpp_aligned_new
expands to the integer literal 201606L
(macro constant)
__cpp_attributes
expands to the integer literal 200809L
(macro constant)
__cpp_binary_literals
expands to the integer literal 201304L
(macro constant)
__cpp_capture_star_this
expands to the integer literal 201603L
(macro constant)
__cpp_constexpr
expands to the integer literal 201603L
(macro constant)
__cpp_decltype
expands to the integer literal 200707L
(macro constant)
__cpp_decltype_auto
expands to the integer literal 201304L
(macro constant)
__cpp_deduction_guides
expands to the integer literal 201703L
(macro constant)
__cpp_delegating_constructors
expands to the integer literal 200604L
(macro constant)
__cpp_enumerator_attributes
expands to the integer literal 201411L
(macro constant)
__cpp_explicit_bool
expands to the integer literal 201806L
(macro constant)
__cpp_fold_expressions
expands to the integer literal 201603L
(macro constant)
__cpp_generic_lambdas
expands to the integer literal 201304L
(macro constant)
__cpp_guaranteed_copy_elision
expands to the integer literal 201606L
(macro constant)
__cpp_hex_float
expands to the integer literal 201603L
(macro constant)
__cpp_if_constexpr
expands to the integer literal 201606L
(macro constant)
__cpp_inheriting_constructors
expands to the integer literal 201511L
(macro constant)
__cpp_init_captures
expands to the integer literal 201304L
(macro constant)
__cpp_initializer_lists
expands to the integer literal 200806L
(macro constant)
__cpp_inline_variables
expands to the integer literal 201606L
(macro constant)
__cpp_lambdas
expands to the integer literal 200907L
(macro constant)
__cpp_namespace_attributes
expands to the integer literal 201411L
(macro constant)
__cpp_noexcept_function_type
expands to the integer literal 201510L
(macro constant)
__cpp_nontype_template_args
expands to the integer literal 201411L
(macro constant)
__cpp_nontype_template_parameter_auto
expands to the integer literal 201606L
(macro constant)
__cpp_nontype_template_parameter_class
expands to the integer literal 201806L
(macro constant)
__cpp_nsdmi
expands to the integer literal 200809L
(macro constant)
__cpp_range_based_for
expands to the integer literal 201603L
(macro constant)
__cpp_raw_strings
expands to the integer literal 200710L
(macro constant)
__cpp_ref_qualifiers
expands to the integer literal 200710L
(macro constant)
__cpp_return_type_deduction
expands to the integer literal 201304L
(macro constant)
__cpp_rvalue_references
expands to the integer literal 200610L
(macro constant)
__cpp_sized_deallocation
expands to the integer literal 201309L
(macro constant)
__cpp_static_assert
expands to the integer literal 201411L
(macro constant)
__cpp_structured_bindings
expands to the integer literal 201606L
(macro constant)
__cpp_template_template_args
expands to the integer literal 201611L
(macro constant)
__cpp_threadsafe_static_init
expands to the integer literal 200806L
(macro constant)
__cpp_unicode_characters
expands to the integer literal 200704L
(macro constant)
__cpp_unicode_literals
expands to the integer literal 200710L
(macro constant)
__cpp_user_defined_literals
expands to the integer literal 200809L
(macro constant)
__cpp_variable_templates
expands to the integer literal 201304L
(macro constant)
__cpp_variadic_templates
expands to the integer literal 200704L
(macro constant)
__cpp_variadic_using
expands to the integer literal 201611L
(macro constant)
(since C++20)

Example

#include <iostream>

//make function factory and use it
#define FUNCTION(name, a) int fun_##name() { return a;}

FUNCTION(abcd, 12)
FUNCTION(fff, 2)
FUNCTION(qqq, 23)

#undef FUNCTION
#define FUNCTION 34
#define OUTPUT(a) std::cout << "output: " #a << '\n'

int main()
{
    std::cout << "abcd: " << fun_abcd() << '\n';
    std::cout << "fff: " << fun_fff() << '\n';
    std::cout << "qqq: " << fun_qqq() << '\n';
    std::cout << FUNCTION << '\n';
    OUTPUT(million);               //note the lack of quotes
}

Output:

abcd: 12
fff: 2
qqq: 23
34
output: million

See also