15 Preprocessing directives [cpp]

15.2 Conditional inclusion [cpp.cond]

has-include-expression:
__has_include ( header-name )
__has_include ( header-name-tokens )
has-attribute-expression:
__has_cpp_attribute ( pp-tokens )
1
#
The expression that controls conditional inclusion shall be an integral constant expression except that identifiers (including those lexically identical to keywords) are interpreted as described below123 and it may contain zero or more defined-macro-expressions, has-include-expressions, has-attribute-expressions, and/or has-embed-expressions as unary operator expressions.
2
#
A defined-macro-expression evaluates to 1 if the identifier is currently defined as a macro name (that is, if it is predefined or if it has one or more active macro definitions ([cpp.import]), for example because it has been the subject of a #define preprocessing directive without an intervening #undef directive with the same subject identifier), 0 if it is not.
3
#
The header or source file identified by the parenthesized preprocessing token sequence in each contained has-include-expression is searched for as if that preprocessing token sequence were the pp-tokens of a #include directive, except that no further macro expansion is performed.
If the preprocessing token sequence does not consist solely of a header-name or cannot be combined ([cpp.include]) into a single header-name preprocessing token, the program is ill-formed.
The has-include-expression evaluates to 1 if the search for the source file succeeds, and to 0 if the search fails.
4
#
The parenthesized preprocessing token sequence of each contained has-embed-expression is processed as if that preprocessing token sequence were the pp-tokens of a #embed directive ([cpp.embed]), except that no further macro expansion is performed.
The has-embed-expression evaluates to:
[Note 1: 
An unrecognized embed-parameter in an has-embed-expression is not ill-formed and is instead treated as not supported.
— end note]
5
#
Each has-attribute-expression is replaced by a non-zero pp-number matching the form of an integer-literal if the implementation supports an attribute with the name specified by interpreting the pp-tokens, after macro expansion, as an attribute-token, and by 0 otherwise.
The program is ill-formed if the pp-tokens do not match the form of an attribute-token.
6
#
For an attribute specified in this document, it is implementation-defined whether the value of the has-attribute-expression is 0 or is given by Table 21.
For other attributes recognized by the implementation, the value is implementation-defined.
[Note 2: 
It is expected that the availability of an attribute can be detected by any non-zero result.
— end note]
Table 21 — __has_cpp_attribute values [tab:cpp.cond.ha]
🔗
Attribute
Value
🔗
assume
202207L
🔗
deprecated
201309L
🔗
fallthrough
201603L
🔗
indeterminate
202403L
🔗
likely
201803L
🔗
maybe_unused
201603L
🔗
no_unique_address
201803L
🔗
nodiscard
201907L
🔗
noreturn
200809L
🔗
unlikely
201803L
7
#
The #ifdef, #ifndef, #elifdef, and #elifndef directives, and the defined conditional inclusion operator, shall treat __has_include, __has_embed, and __has_cpp_attribute as if they were the names of defined macros.
The identifiers __has_include, __has_embed, and __has_cpp_attribute shall not appear in any context not mentioned in this subclause.
8
#
Each preprocessing token that remains (in the list of preprocessing tokens that will become the controlling expression) after all macro replacements have occurred shall be in the lexical form of a token.
9
#
Preprocessing directives of the forms
# if      constant-expression new-line group
# elif    constant-expression new-line group
check whether the controlling constant expression evaluates to nonzero.
10
#
Prior to evaluation, macro invocations in the list of preprocessing tokens that will become the controlling constant expression are replaced (except for those macro names modified by the defined unary operator), just as in normal text.
If replacement of macros in the preprocessing tokens following the sequence __has_embed ( and before a matching ) (possibly produced by macro expansion) encounters a preprocessing token that is one of the identifiers limit, prefix, suffix, or if_empty and that identifier is defined as a macro ([cpp.replace.general]), the program is ill-formed.
If the preprocessing token defined is generated as a result of this replacement process or use of the defined unary operator does not match one of the two specified forms prior to macro replacement, the program is ill-formed, no diagnostic required.
11
#
After all replacements due to macro expansion and evaluations of defined-macro-expressions, has-include-expressions, has-embed-expressions, and has-attribute-expressions have been performed, all remaining identifiers and keywords, except for true and false, are replaced with the pp-number 0, and then each preprocessing token is converted into a token.
[Note 3: 
An alternative token is not an identifier, even when its spelling consists entirely of letters and underscores.
Therefore it is not subject to this replacement.
— end note]
12
#
The resulting tokens comprise the controlling constant expression which is evaluated according to the rules of [expr.const] using arithmetic that has at least the ranges specified in [support.limits].
For the purposes of this token conversion and evaluation all signed and unsigned integer types act as if they have the same representation as, respectively, intmax_t or uintmax_t ([cstdint.syn]).
[Note 4: 
Thus on an implementation where std​::​numeric_limits<int>​::​max() is 0x7FFF and std​::​numeric_limits<unsigned int>​::​max() is 0xFFFF, the integer literal 0x8000 is signed and positive within a #if expression even though it is unsigned in translation phase 7.
— end note]
This includes interpreting character-literals according to the rules in [lex.ccon].
[Note 5: 
The associated character encodings of literals are the same in #if and #elif directives and in any expression.
— end note]
Each subexpression with type bool is subjected to integral promotion before processing continues.
13
#
Preprocessing directives of the forms
# ifdef    identifier new-line group
# ifndef   identifier new-line group
# elifdef identifier new-line group
# elifndef identifier new-line group
check whether the identifier is or is not currently defined as a macro name.
Their conditions are equivalent to #if defined identifier, #if !defined identifier, #elif defined identifier, and #elif !defined identifier, respectively.
14
#
Each directive's condition is checked in order.
If it evaluates to false (zero), the group that it controls is skipped: directives are processed only through the name that determines the directive in order to keep track of the level of nested conditionals; the rest of the directives' preprocessing tokens are ignored, as are the other preprocessing tokens in the group.
Only the first group whose control condition evaluates to true (nonzero) is processed; any following groups are skipped and their controlling directives are processed as if they were in a group that is skipped.
If none of the conditions evaluates to true, and there is a #else directive, the group controlled by the #else is processed; lacking a #else directive, all the groups until the #endif are skipped.124
15
#
[Example 1: 
This demonstrates a way to include a library optional facility only if it is available: #if __has_include(<optional>) # include <optional> # if __cpp_lib_optional >= 201603 # define have_optional 1 # endif #elif __has_include(<experimental/optional>) # include <experimental/optional> # if __cpp_lib_experimental_optional >= 201411 # define have_optional 1 # define experimental_optional 1 # endif #endif #ifndef have_optional # define have_optional 0 #endif
— end example]
16
#
[Example 2: 
This demonstrates a way to use the attribute [[acme​::​deprecated]] only if it is available.
#if __has_cpp_attribute(acme::deprecated) # define ATTR_DEPRECATED(msg) [[acme::deprecated(msg)]] #else # define ATTR_DEPRECATED(msg) [[deprecated(msg)]] #endif ATTR_DEPRECATED("This function is deprecated") void anvil(); — end example]
123)123)
Because the controlling constant expression is evaluated during translation phase 4, all identifiers either are or are not macro names — there simply are no keywords, enumeration constants, etc.
124)124)
As indicated by the syntax, a preprocessing token cannot follow a #else or #endif directive before the terminating new-line character.
However, comments can appear anywhere in a source file, including within a preprocessing directive.