%!TEX root = std.tex

\rSec0[cpp]{Preprocessing directives}%

\indextext{preprocessing directive|(}

\indextext{compiler control line|see{preprocessing directive}}%

\indextext{control line|see{preprocessing directive}}%

\indextext{directive, preprocessing|see{preprocessing directive}}

\gramSec[gram.cpp]{Preprocessing directives}

\rSec1[cpp.pre]{Preamble}

\begin{bnf}

\nontermdef{preprocessing-file}\br

\opt{group}\br

module-file

\end{bnf}

\begin{bnf}

\nontermdef{module-file}\br

\opt{line-directives} \opt{pp-global-module-fragment} pp-module \opt{group} \opt{pp-private-module-fragment}

\end{bnf}

\begin{bnf}

\nontermdef{pp-global-module-fragment}\br

\keyword{module} \terminal{;} new-line \opt{group}

\end{bnf}

\begin{bnf}

\nontermdef{pp-private-module-fragment}\br

\keyword{module} \terminal{:} \keyword{private} \terminal{;} new-line \opt{group}

\end{bnf}

\begin{bnf}

\nontermdef{group}\br

group-part\br

group group-part

\end{bnf}

\begin{bnf}

\nontermdef{group-part}\br

control-line\br

if-section\br

text-line\br

\terminal{\#} conditionally-supported-directive

\end{bnf}

\begin{bnf}

\nontermdef{control-line}\br

\terminal{\# include} pp-tokens new-line\br

pp-import\br

\terminal{\# embed \ } pp-tokens new-line\br

\terminal{\# define } identifier replacement-list new-line\br

\terminal{\# define } identifier lparen \opt{identifier-list} \terminal{)} replacement-list new-line\br

\terminal{\# define } identifier lparen \terminal{... )} replacement-list new-line\br

\terminal{\# define } identifier lparen identifier-list \terminal{, ... )} replacement-list new-line\br

\terminal{\# undef \ } identifier new-line\br

line-directive\br

\terminal{\# error \ } \opt{pp-tokens} new-line\br

\terminal{\# warning} \opt{pp-tokens} new-line\br

\terminal{\# pragma } \opt{pp-tokens} new-line\br

\terminal{\# }new-line

\end{bnf}

\begin{bnf}

\nontermdef{line-directives}\br

line-directive \opt{line-directives}

\end{bnf}

\begin{bnf}

\nontermdef{if-section}\br

if-group \opt{elif-groups} \opt{else-group} endif-line

\end{bnf}

\begin{bnf}

\nontermdef{if-group}\br

\terminal{\# if \ \ \ \ } constant-expression new-line \opt{group}\br

\terminal{\# ifdef \ } identifier new-line \opt{group}\br

\terminal{\# ifndef } identifier new-line \opt{group}

\end{bnf}

\begin{bnf}

\nontermdef{elif-groups}\br

elif-group \opt{elif-groups}

\end{bnf}

\begin{bnf}

\nontermdef{elif-group}\br

\terminal{\# elif \ \ \ } constant-expression new-line \opt{group}\br

\terminal{\# elifdef } identifier new-line \opt{group}\br

\terminal{\# elifndef} identifier new-line \opt{group}

\end{bnf}

\begin{bnf}

\nontermdef{else-group}\br

\terminal{\# else \ \ } new-line \opt{group}

\end{bnf}

\begin{bnf}

\nontermdef{endif-line}\br

\terminal{\# endif \ } new-line

\end{bnf}

\begin{bnf}

\nontermdef{text-line}\br

\opt{pp-tokens} new-line

\end{bnf}

\begin{bnf}

\nontermdef{conditionally-supported-directive}\br

pp-tokens new-line

\end{bnf}

\begin{bnf}

\nontermdef{lparen}\br

\descr{a \terminal{(} character not immediately preceded by whitespace}

\end{bnf}

\begin{bnf}

\nontermdef{identifier-list}\br

identifier\br

identifier-list \terminal{,} identifier

\end{bnf}

\begin{bnf}

\nontermdef{replacement-list}\br

\opt{pp-tokens}

\end{bnf}

\begin{bnf}

\nontermdef{pp-tokens}\br

preprocessing-token \opt{pp-tokens}

\end{bnf}

\begin{bnf}

\nontermdef{embed-parameter-seq}\br

embed-parameter \opt{embed-parameter-seq}

\end{bnf}

\begin{bnf}

\nontermdef{embed-parameter}\br

embed-standard-parameter\br

embed-prefixed-parameter

\end{bnf}

\begin{bnf}

\nontermdef{embed-standard-parameter}\br

\terminal{limit} \terminal{(} pp-balanced-token-seq \terminal{)}\br

\terminal{prefix} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}\br

\terminal{suffix} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}\br

\terminal{if_empty} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}

\end{bnf}

\begin{bnf}

\nontermdef{embed-prefixed-parameter}\br

identifier :: identifier\br

identifier :: identifier \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}

\end{bnf}

\begin{bnf}

\nontermdef{pp-balanced-token-seq}\br

pp-balanced-token \opt{pp-balanced-token-seq}

\end{bnf}

\begin{bnf}

\nontermdef{pp-balanced-token}\br

\terminal{(} \opt{pp-balanced-token-seq} \terminal{)}\br

\terminal{[} \opt{pp-balanced-token-seq} \terminal{]}\br

\terminal{\{} \opt{pp-balanced-token-seq} \terminal{\}}\br

\textnormal{any} pp-token \textnormal{except:}\br

\bnfindent\textnormal{parenthesis (\unicode{0028}{left parenthesis} and \unicode{0029}{right parenthesis}),}\br

\bnfindent\textnormal{bracket (\unicode{005b}{left square bracket} and \unicode{005d}{right square bracket}), or}\br

\bnfindent\textnormal{brace (\unicode{007b}{left curly bracket} and \unicode{007d}{right curly bracket}).}

\end{bnf}

\begin{bnf}

\nontermdef{new-line}\br

\descr{the new-line character}

\end{bnf}

\pnum

The implementation can

process and skip sections of source files conditionally,

include other source files,

import macros from header units,

and replace macros.

These capabilities are called

\defn{preprocessing},

because conceptually they occur

before translation of the resulting translation unit.

\pnum

A \defn{preprocessing directive} consists of a sequence of preprocessing tokens

that satisfies the following constraints:

At the start of translation phase 4,

the first preprocessing token in the sequence,

referred to as a \defnadj{directive-introducing}{token},

begins with the first character in the source file

(optionally after whitespace containing no new-line characters) or

follows whitespace containing at least one new-line character,

and is

\begin{itemize}

\item

a \tcode{\#} preprocessing token, or

\item

an \keyword{import} preprocessing token

immediately followed on the same logical source line by a

\grammarterm{header-name},

\tcode{<},

\grammarterm{identifier}, or

\tcode{:}

preprocessing token, or

\item

a \keyword{module} preprocessing token

immediately followed on the same logical source line by an

\grammarterm{identifier},

\tcode{:}, or

\tcode{;}

preprocessing token, or

\item

an \keyword{export} preprocessing token

immediately followed on the same logical source line by

one of the two preceding forms.

\end{itemize}

The last preprocessing token in the sequence is the first preprocessing token within the sequence that

is immediately followed by whitespace containing a new-line character.

\begin{note}

A new-line character ends the preprocessing directive even if it occurs

within what would otherwise be an invocation of a function-like macro.

\end{note}

\begin{example}

\begin{codeblock}

# // preprocessing directive

module ; // preprocessing directive

export module leftpad; // preprocessing directive

import <string>; // preprocessing directive

export import "squee"; // preprocessing directive

import rightpad; // preprocessing directive

import :part; // preprocessing directive

module // not a preprocessing directive

; // not a preprocessing directive

export // not a preprocessing directive

import // not a preprocessing directive

foo; // not a preprocessing directive

export // not a preprocessing directive

import foo; // preprocessing directive (ill-formed at phase 7)

import :: // not a preprocessing directive

import -> // not a preprocessing directive

\end{codeblock}

\end{example}

\pnum

A sequence of preprocessing tokens is only a \grammarterm{text-line}

if it does not begin with a directive-introducing token.

\begin{example}

\begin{codeblock}

using module = int;

module i; // not a \grammarterm{text-line} and not a \grammarterm{control-line}

int foo() {

return i;

}

\end{codeblock}

The example is not a valid \grammarterm{preprocessing-file}.

\end{example}

A sequence of preprocessing tokens is only a \grammarterm{conditionally-supported-directive}

if it does not begin with any of the directive names

appearing after a \tcode{\#} in the syntax.

A \grammarterm{conditionally-supported-directive} is

conditionally-supported with

\impldef{additional supported forms of preprocessing directive}

semantics.

\pnum

If one of the \grammarterm{pp-tokens} of a \tcode{\#embed} directive

(before macro replacement) is the \grammarterm{identifier}

\tcode{limit}, \tcode{prefix}, \tcode{suffix}, or \tcode{if_empty}

and that \grammarterm{identifier} is defined

as a macro\iref{cpp.replace.general}, the program is ill-formed.

Any \grammarterm{embed-prefixed-parameter} is conditionally-supported,

with \impldef{supported forms of \#embed prefix parameters} semantics.

\pnum

At the start of phase 4 of translation,

the \grammarterm{group} of a \grammarterm{pp-global-module-fragment} shall

contain neither a \grammarterm{text-line} nor a \grammarterm{pp-import}.

\pnum

When in a group that is skipped\iref{cpp.cond}, the directive

syntax is relaxed to allow any sequence of preprocessing tokens to occur between

the directive name and the following new-line character.

\pnum

The only whitespace characters that shall appear

between preprocessing tokens

within a preprocessing directive

(from just after the directive-introducing token

through just before the terminating new-line character)

are \unicode{0020}{space} and \unicode{0009}{character tabulation}

(including spaces that have replaced comments

or possibly other whitespace characters

in translation phase 3).

\pnum

The preprocessing tokens within a preprocessing directive

are not subject to macro expansion unless otherwise stated.

\begin{example}

In:

\begin{codeblock}

#define EMPTY

EMPTY # include <file.h>

\end{codeblock}

the sequence of preprocessing tokens on the second line is \textit{not}

a preprocessing directive, because it does not begin with a \tcode{\#} at the start of

translation phase 4, even though it will do so after the macro \tcode{EMPTY}

has been replaced.

\end{example}

\rSec1[cpp.cond]{Conditional inclusion}%

\indextext{preprocessing directive!conditional inclusion}%

\indextext{inclusion!conditional|see{preprocessing directive, conditional inclusion}}

\indextext{\idxcode{defined}}%

\begin{bnf}

\nontermdef{defined-macro-expression}\br

\terminal{defined} identifier\br

\terminal{defined (} identifier \terminal{)}

\end{bnf}

\begin{bnf}

\nontermdef{h-preprocessing-token}\br

\textnormal{any \grammarterm{preprocessing-token} other than \terminal{>}}

\end{bnf}

\begin{bnf}

\nontermdef{h-pp-tokens}\br

h-preprocessing-token \opt{h-pp-tokens}

\end{bnf}

\begin{bnf}

\nontermdef{header-name-tokens}\br

plain-string-literal\br

\terminal{<} h-pp-tokens \terminal{>}

\end{bnf}

\indextext{\idxxname{has_include}}%

\begin{bnf}

\nontermdef{has-include-expression}\br

\terminal{\xname{has_include}} \terminal{(} header-name \terminal{)}\br

\terminal{\xname{has_include}} \terminal{(} header-name-tokens \terminal{)}

\end{bnf}

\indextext{\idxxname{has_embed}}%

\begin{bnf}

\nontermdef{has-embed-expression}\br

\terminal{\xname{has_embed}} \terminal{(} header-name \opt{pp-balanced-token-seq} \terminal{)}\br

\terminal{\xname{has_embed}} \terminal{(} header-name-tokens \opt{pp-balanced-token-seq} \terminal{)}

\end{bnf}

\indextext{\idxxname{has_cpp_attribute}}%

\begin{bnf}

\nontermdef{has-attribute-expression}\br

\terminal{\xname{has_cpp_attribute} (} pp-tokens \terminal{)}

\end{bnf}

\pnum

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 below

\begin{footnote}

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.

\end{footnote}

and it may contain zero or more

\grammarterm{defined-macro-expression}{s},

\grammarterm{has-include-expression}{s},

\grammarterm{has-attribute-expression}{s},

and/or \grammarterm{has-embed-expression}{s}

as unary operator expressions.

A \grammarterm{defined-macro-expression} shall not appear

within a \grammarterm{has-include-expression} or \grammarterm{has-embed-expression}.

\pnum

A \grammarterm{defined-macro-expression} evaluates to \tcode{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\iref{cpp.import},

for example because

it has been the subject of a

\tcode{\#define}

preprocessing directive

without an intervening

\tcode{\#undef}

directive with the same subject identifier), \tcode{0} if it is not.

\pnum

The header or source file identified by

the parenthesized preprocessing token sequence

in each contained \grammarterm{has-include-expression}

is searched for as if that preprocessing token sequence

were the \grammarterm{pp-tokens} of a \tcode{\#include} directive,

except that no further macro expansion is performed.

If the preprocessing token sequence does not consist solely of a \grammarterm{header-name}

or cannot be combined\iref{cpp.include} into a single

\grammarterm{header-name} preprocessing token, the program is ill-formed.

The \grammarterm{has-include-expression} evaluates

to \tcode{1} if the search for the source file succeeds, and

to \tcode{0} if the search fails.

\pnum

The parenthesized preprocessing token sequence of each contained

\grammarterm{has-embed-expression} is processed as if that

preprocessing token sequence were the \grammarterm{pp-tokens}

of a \tcode{\#embed} directive\iref{cpp.embed},

except that no further macro expansion is performed.

The \grammarterm{has-embed-expression} evaluates to:

\begin{itemize}

\item

\mname{STDC_EMBED_FOUND} if the search for the resource succeeds,

all the given \grammarterm{embed-parameter}s in the \grammarterm{embed-parameter-seq}

are supported, and the resource is not empty.

\item

Otherwise, \mname{STDC_EMBED_EMPTY} if the search for the resource succeeds,

all the given \grammarterm{embed-parameter}s in the \grammarterm{embed-parameter-seq}

are supported, and the resource is empty.

\item

Otherwise, \mname{STDC_EMBED_NOT_FOUND}.

\end{itemize}

\begin{note}

An unrecognized \grammarterm{embed-parameter} in an \grammarterm{has-embed-expression}

is not ill-formed and is instead treated as not supported.

\end{note}

\pnum

Each \grammarterm{has-attribute-expression} is replaced by

a non-zero \grammarterm{pp-number}

matching the form of an \grammarterm{integer-literal}

if the implementation supports an attribute

with the name specified by interpreting

the \grammarterm{pp-tokens}, after macro expansion,

as an \grammarterm{attribute-token},

and by \tcode{0} otherwise.

The program is ill-formed if the \grammarterm{pp-tokens}

do not match the form of an \grammarterm{attribute-token}.

\pnum

For an attribute specified in this document,

it is \impldef{value of \grammarterm{has-attribute-expression}

for standard attributes}

whether the value of the \grammarterm{has-attribute-expression}

is \tcode{0} or is given by \tref{cpp.cond.ha}.

For other attributes recognized by the implementation,

the value is

\impldef{value of \grammarterm{has-attribute-expression}

for non-standard attributes}.

\begin{note}

It is expected

that the availability of an attribute can be detected by any non-zero result.

\end{note}

\begin{floattable}{\xname{has_cpp_attribute} values}{cpp.cond.ha}

{ll}

\topline

\lhdr{Attribute} & \rhdr{Value} \\ \rowsep

\tcode{assume} & \tcode{202207L} \\

\tcode{deprecated} & \tcode{201309L} \\

\tcode{fallthrough} & \tcode{201603L} \\

\tcode{indeterminate} & \tcode{202403L} \\

\tcode{likely} & \tcode{201803L} \\

\tcode{maybe_unused} & \tcode{201603L} \\

\tcode{no_unique_address} & \tcode{201803L} \\

\tcode{nodiscard} & \tcode{201907L} \\

\tcode{noreturn} & \tcode{200809L} \\

\tcode{unlikely} & \tcode{201803L} \\

\end{floattable}

\pnum

The

\tcode{\#ifdef}, \tcode{\#ifndef}, \tcode{\#elifdef}, and \tcode{\#elifndef}

directives, and

the \tcode{defined} conditional inclusion operator,

shall treat \xname{has_include}, \xname{has_embed}, and \xname{has_cpp_attribute}

as if they were the names of defined macros.

The identifiers \xname{has_include}, \xname{has_embed}, and \xname{has_cpp_attribute}

shall not appear in any context not mentioned in this subclause.

\pnum

Preprocessing directives of the forms

\begin{ncsimplebnf}

\indextext{\idxcode{\#if}}%

\terminal{\# if \ \ \ \ } constant-expression new-line \opt{group}\br

\indextext{\idxcode{\#elif}}%

\terminal{\# elif \ \ } constant-expression new-line \opt{group}

\end{ncsimplebnf}

check whether the controlling constant expression evaluates to nonzero.

\pnum

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

\tcode{defined}

unary operator),

just as in normal text.

If replacement of macros in the preprocessing tokens following the sequence

\tcode{\xname{has_embed} (} and before a matching \tcode{)}

(possibly produced by macro expansion)

encounters a preprocessing token that is one of the \grammarterm{identifier}s

\tcode{limit}, \tcode{prefix}, \tcode{suffix}, or \tcode{if_empty}

and that \grammarterm{identifier} is defined

as a macro\iref{cpp.replace.general}, the program is ill-formed.

If the preprocessing token

\tcode{defined}

is generated as a result of this replacement process

or use of the

\tcode{defined}

unary operator does not match one of the two specified forms

prior to macro replacement,

the program is ill-formed, no diagnostic required.

\pnum

After all replacements due to macro expansion and

evaluations of

\grammarterm{defined-macro-expression}s,

\grammarterm{has-include-expression}s,

\grammarterm{has-embed-expression}s, and

\grammarterm{has-attribute-expression}s

have been performed,

all remaining identifiers (including those lexically identical to keywords),

except for

\tcode{true}

and

\tcode{false},

are replaced with the \grammarterm{pp-number}

\tcode{0},

and then each preprocessing token is converted into a token.

\begin{note}

An alternative

token\iref{lex.digraph} is not an identifier,

even when its spelling consists entirely of letters and underscores.

Therefore it is not subject to this replacement.

\end{note}

\pnum

The resulting tokens comprise the controlling constant expression

which is evaluated according to the rules of~\ref{expr.const.core}

using arithmetic that has at least the ranges specified

in~\ref{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,

\tcode{intmax_t} or \tcode{uintmax_t}\iref{cstdint.syn}.

\begin{note}

Thus on an

implementation where \tcode{std::numeric_limits<int>::max()} is \tcode{0x7FFF}

and \tcode{std::numeric_limits<unsigned int>::max()} is \tcode{0xFFFF},

the integer literal \tcode{0x8000} is signed and positive within a \tcode{\#if}

expression even though it is unsigned in translation phase

7\iref{lex.phases}.

\end{note}

This includes interpreting \grammarterm{character-literal}s

according to the rules in \ref{lex.ccon}.

\begin{note}

The associated character encodings of literals are the same

in \tcode{\#if} and \tcode{\#elif} directives and in any expression.

\end{note}

Each subexpression with type

\tcode{bool}

is subjected to integral promotion before processing continues.

\pnum

Preprocessing directives of the forms

\begin{ncsimplebnf}

\terminal{\# ifdef \ \ } identifier new-line \opt{group}\br

\indextext{\idxcode{\#ifdef}}%

\terminal{\# ifndef \ } identifier new-line \opt{group}\br

\indextext{\idxcode{\#ifndef}}%

\terminal{\# elifdef } identifier new-line \opt{group}\br

\indextext{\idxcode{\#elifdef}}%

\terminal{\# elifndef} identifier new-line \opt{group}

\indextext{\idxcode{\#elifndef}}%

\end{ncsimplebnf}

check whether the identifier is or is not currently defined as a macro name.

Their conditions are equivalent to

\tcode{\#if} \tcode{defined} \grammarterm{identifier},

\tcode{\#if} \tcode{!defined} \grammarterm{identifier},

\tcode{\#elif} \tcode{defined} \grammarterm{identifier}, and

\tcode{\#elif} \tcode{!defined} \grammarterm{identifier},

respectively.

\pnum

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 directive 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

\tcode{\#else}

\indextext{\idxcode{\#else}}%

directive,

the group controlled by the

\tcode{\#else}

is processed; lacking a

\tcode{\#else}

directive, all the groups until the

\tcode{\#endif}

\indextext{\idxcode{\#endif}}%

are skipped.%

\begin{footnote}

As indicated by the syntax,

a preprocessing token cannot follow a

\tcode{\#else}

or

\tcode{\#endif}

directive before the terminating new-line character.

However,

comments can appear anywhere in a source file,

including within a preprocessing directive.

\end{footnote}

\pnum

\begin{example}

This demonstrates a way to include a library \tcode{optional} facility

only if it is available:

\begin{codeblock}

#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{codeblock}

\end{example}

\pnum

\begin{example}

This demonstrates a way to use the attribute \tcode{[[acme::deprecated]]}

only if it is available.

\begin{codeblock}

#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{codeblock}

\end{example}

\rSec1[cpp.include]{Source file inclusion}

\indextext{preprocessing directive!header inclusion}

\indextext{preprocessing directive!source-file inclusion}

\indextext{inclusion!source file|see{preprocessing directive, source-file inclusion}}%

\indextext{\idxcode{\#include}}%

\pnum

A \defnadj{header}{search} for a sequence of characters

searches a sequence of places for a header

identified uniquely by that sequence of characters.

How the places are determined or the header identified

is \impldef{determination of places and identification of headers during header search}.

\pnum

A \defnadj{source file}{search} for a sequence of characters

attempts to identify a source file that is named by the sequence of characters.

The named source file is searched for

in an \impldef{search for source files during source file search} manner.

If the implementation does not support a source file search

for that sequence of characters, or if the search fails,

the result of the source file search

is the result of a header search for the same sequence of characters.

\pnum

A preprocessing directive of the form

\begin{ncsimplebnf}

\terminal{\# include} header-name new-line

\end{ncsimplebnf}

causes the replacement of that directive by the entire contents

of the header or source file identified by \grammarterm{header-name}.

\pnum

If the \grammarterm{header-name} is of the form

\begin{ncsimplebnf}

\terminal{<} h-char-sequence \terminal{>}

\end{ncsimplebnf}

a header is identified by a header search for the sequence of characters

of the \grammarterm{h-char-sequence}.

\pnum

If the \grammarterm{header-name} is of the form

\begin{ncsimplebnf}

\terminal{"} q-char-sequence \terminal{"}

\end{ncsimplebnf}

the source file or header is identified by a source file search

for the sequence of characters of the \grammarterm{q-char-sequence}.

\pnum

If a header search fails, or if a source file search or header search

identifies a header or source file that cannot be processed by the implementation,

the program is ill-formed.

\begin{note}

If the header or source file cannot be processed,

the program is ill-formed even when evaluating \xname{has_include}.

\end{note}

\pnum

A preprocessing directive of the form

\begin{ncsimplebnf}

\terminal{\# include} pp-tokens new-line

\end{ncsimplebnf}

(that does not match the previous form) is permitted.

The preprocessing tokens after

\tcode{include}

in the directive are processed just as in normal text

(i.e., each identifier currently defined as a macro name is replaced by its

replacement list of preprocessing tokens).

The resulting sequence of preprocessing tokens shall be of the form

\begin{ncsimplebnf}

header-name-tokens

\end{ncsimplebnf}

An attempt is then made to form a \grammarterm{header-name}

preprocessing token\iref{lex.header} from the whitespace and the characters

of the spellings of the \grammarterm{header-name-tokens};

the treatment of whitespace

is \impldef{treatment of whitespace when processing a \tcode{\#include} directive}.

If the attempt succeeds, the directive with the so-formed \grammarterm{header-name}

is processed as specified for the previous form.

Otherwise, the program is ill-formed, no diagnostic required.

\begin{note}

Adjacent \grammarterm{string-literal}s are not concatenated into

a single \grammarterm{string-literal}

(see the translation phases in~\ref{lex.phases});

thus, an expansion that results in two \grammarterm{string-literal}s is an

invalid directive.

\end{note}

\pnum

The implementation shall provide unique mappings for

sequences consisting of one or more

\grammarterm{nondigit}{s} or \grammarterm{digit}{s}\iref{lex.name}

followed by a period

(\tcode{.})

and a single

\grammarterm{nondigit}.

The first character shall not be a \grammarterm{digit}.

The implementation may ignore distinctions of alphabetical case.

\pnum

A

\tcode{\#include}

preprocessing directive may appear

in a source file that has been read because of a

\tcode{\#include}

directive in another file,

up to an \impldef{nesting limit for \tcode{\#include} directives} nesting limit.

\pnum

If the header identified by the \grammarterm{header-name}

denotes an importable header\iref{module.import},

it is

\impldef{whether source file inclusion of importable header

is replaced with \tcode{import} directive}

whether the \tcode{\#include} preprocessing directive

is instead replaced by an \tcode{import} directive\iref{cpp.import} of the form

\begin{ncbnf}

\keyword{import} header-name \terminal{;} new-line

\end{ncbnf}

\pnum

\begin{note}

An implementation can provide a mechanism for making arbitrary

source files available to the \tcode{< >} search.

However, using the \tcode{< >} form for headers provided

with the implementation and the \tcode{" "} form for sources

outside the control of the implementation

achieves wider portability. For instance:

\begin{codeblock}

#include <stdio.h>

#include <unistd.h>

#include "usefullib.h"

#include "myprog.h"

\end{codeblock}

\end{note}

\pnum

\begin{example}

This illustrates macro-replaced

\tcode{\#include}

directives:

\begin{codeblock}

#if VERSION == 1

#define INCFILE "vers1.h"

#elif VERSION == 2

#define INCFILE "vers2.h" // and so on

#else

#define INCFILE "versN.h"

#endif

#include INCFILE

\end{codeblock}

\end{example}

\rSec1[cpp.embed]{Resource inclusion}

\indextext{preprocessing directive!embed a resource}

\indextext{\idxcode{\#embed}}%

\rSec2[cpp.embed.gen]{General}

\pnum

A \defnadj{bracket resource}{search} for a sequence of characters

searches a sequence of places for a resource identified uniquely

by that sequence of characters.

How the places are determined or the resource identified

is \impldef{determination of places and identification of resources during bracket resource search}.

\pnum

A \defnadj{quote resource}{search} for a sequence of characters

attempts to identify a resource that is named by the sequence of characters.

The named resource is searched for

in an \impldef{search for resources during quote resource search} manner.

If the implementation does not support a quote resource search

for that sequence of characters, or if the search fails,

the result of the quote resource search

is the result of a bracket resource search for the same sequence of characters.

\pnum

A preprocessing directive of the form

\begin{ncsimplebnf}

\terminal{\# embed} header-name \opt{pp-tokens} new-line

\end{ncsimplebnf}

causes the replacement of that directive

by preprocessing tokens derived from data

in the resource identified by \grammarterm{header-name},

as specified below.

\pnum

If the \grammarterm{header-name} is of the form

\begin{ncsimplebnf}

\terminal{<} h-char-sequence \terminal{>}

\end{ncsimplebnf}

the resource is identified by a bracket resource search

for the sequence of characters of the \grammarterm{h-char-sequence}.

\pnum

If the \grammarterm{header-name} is of the form

\begin{ncsimplebnf}

\terminal{"} q-char-sequence \terminal{"}

\end{ncsimplebnf}

the resource is identified by a quote resource search

for the sequence of characters of the \grammarterm{q-char-sequence}.

\pnum

If a bracket resource search fails,

or if a quote or bracket resource search identifies a resource

that cannot be processed by the implementation, the program is ill-formed.

\begin{note}

If the resource cannot be processed, the program is ill-formed

even when processing \tcode{\#embed} with \tcode{limit(0)}\iref{cpp.embed.param.limit}

or evaluating \xname{has_embed}.

\end{note}

\pnum

\recommended A mechanism similar to, but distinct from, the

\impldef{sequence of places searched for a header}

search paths used for \tcode{\#include}\iref{cpp.include}

is encouraged.

\pnum

Either form of the \tcode{\#embed} directive processes the

\grammarterm{pp-tokens}, if present, just as in normal text.

The \grammarterm{pp-tokens} shall then have the form

\grammarterm{embed-parameter-seq}.

\pnum

A resource is a source of data accessible from the translation environment.

A resource has an \defn{implementation-resource-width}, which is the

\impldef{size in bits of a resource}

size in bits of the resource.

If the implementation-resource-width is not an integral multiple of

\libmacro{CHAR_BIT}, the program is ill-formed.

Let \defn{implementation-resource-count} be

implementation-resource-width divided by \libmacro{CHAR_BIT}.

Every resource also has a \defn{resource-count}, which is

\begin{itemize}

\item

the value as computed from the optionally-provided \tcode{limit}

\grammarterm{embed-parameter}\iref{cpp.embed.param.limit}, if present;

\item

otherwise, the implementation-resource-count.

\end{itemize}

A resource is empty if the resource-count is zero.

\pnum

\begin{example}

\begin{codeblock}

// ill-formed if the implementation-resource-width is 6 bits

#embed "6_bits.bin"

\end{codeblock}

\end{example}

\pnum

The \tcode{\#embed} directive is replaced by a comma-separated list of integer

literals of type \tcode{int}, unless otherwise modified by embed

parameters\iref{cpp.embed.param}.

\pnum

The integer literals in the comma-separated list correspond to

resource-count consecutive calls to \tcode{std::fgetc}\iref{cstdio.syn}

from the resource, as a binary file.

If any call to \tcode{std::fgetc} returns \tcode{EOF}, the program is

ill-formed.

\pnum

\recommended The value of each integer literal should closely represent

the bit stream of the resource unmodified.

This can require an implementation to consider potential differences between

translation and execution environments, as well as any other applicable

sources of mismatch.

\begin{example}

\begin{codeblock}

#include <cstring>

#include <cstddef>

#include <fstream>

#include <vector>

#include <cassert>

int main() {

// If the file is the same as the resource in the translation environment, no assert in this program should fail.

constexpr unsigned char d[] = {

#embed <data.dat>

};

const std::vector<unsigned char> vec_d = {

#embed <data.dat>

};

constexpr std::size_t expected_size = sizeof(d);

// same file in execution environment as was embedded

std::ifstream f_source("data.dat", std::ios::binary | std::ios::in);

unsigned char runtime_d[expected_size];

char* ifstream_ptr = reinterpret_cast<char*>(runtime_d);

assert(!f_source.read(ifstream_ptr, expected_size));

std::size_t ifstream_size = f_source.gcount();

assert (ifstream_size == expected_size);

int is_same = std::memcmp(&d[0], ifstream_ptr, ifstream_size);

assert(is_same == 0);

int is_same_vec = std::memcmp(vec_d.data(), ifstream_ptr, ifstream_size);

assert(is_same_vec == 0);

}

\end{codeblock}

\end{example}

\begin{example}

\begin{codeblock}

int i = {

#embed "i.dat"

}; // well-formed if \tcode{i.dat} produces a single value

int i2 =

#embed "i.dat"

; // also well-formed if \tcode{i.dat} produces a single value

struct s {

double a, b, c;

struct { double e, f, g; } x;