\rSec0[cpp]{Preprocessing directives}%

\indextext{preprocessing directives|(}

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

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

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

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

that satisfies the following constraints:

The first token in the sequence is a

\tcode{\#}

preprocessing token that (at the start of translation phase 4)

is either the first character in the source file

(optionally after white space containing no new-line characters)

or that follows white space containing at least one new-line character.

The last token in the sequence is the first new-line character

that follows the first token in the sequence.\footnote{Thus,

preprocessing directives are commonly called ``lines.''

These ``lines'' have no other syntactic significance,

as all white space is equivalent except in certain situations

during preprocessing (see the

\tcode{\#}

character string literal creation operator in~\ref{cpp.stringize}, for example).}

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

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

\begin{bnf}

\nontermdef{preprocessing-file}\br

group\opt

\end{bnf}

\begin{bnf}

\nontermdef{group}\br

group-part\br

group group-part

\end{bnf}

\begin{bnf}

\nontermdef{group-part}\br

if-section\br

control-line\br

text-line\br

\terminal{\#} non-directive

\end{bnf}

\begin{bnf}

\nontermdef{if-section}\br

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

\end{bnf}

\begin{bnftab}

\nontermdef{if-group}\br

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

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

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

\end{bnftab}

\begin{bnf}

\nontermdef{elif-groups}\br

elif-group\br

elif-groups elif-group

\end{bnf}

\begin{bnftab}

\nontermdef{elif-group}\br

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

\end{bnftab}

\begin{bnftab}

\nontermdef{else-group}\br

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

\end{bnftab}

\begin{bnftab}

\nontermdef{endif-line}\br

\>\terminal{\# endif}\>\>new-line

\end{bnftab}

\begin{bnftab}

\nontermdef{control-line}\br

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

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

\>\terminal{\# define}\>\>identifier lparen identifier-list\opt \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

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

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

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

\>\terminal{\# }new-line

\end{bnftab}

\begin{bnf}

\nontermdef{text-line}\br

pp-tokens\opt{} new-line

\end{bnf}

\begin{bnf}

\nontermdef{non-directive}\br

pp-tokens new-line

\end{bnf}

\begin{bnf}

\nontermdef{lparen}\br

\descr{a \terminal{(} character not immediately preceded by white-space}

\end{bnf}

\begin{bnf}

\nontermdef{identifier-list}\br

identifier\br

identifier-list \terminal{,} identifier

\end{bnf}

\begin{bnf}

\nontermdef{replacement-list}\br

pp-tokens\opt

\end{bnf}

\begin{bnf}

\nontermdef{pp-tokens}\br

preprocessing-token\br

pp-tokens preprocessing-token

\end{bnf}

\begin{bnf}

\nontermdef{new-line}\br

\descr{the new-line character}

\end{bnf}

A text line shall not begin with a \tcode{\#} preprocessing token.

A non-directive shall not begin with any of the directive names appearing in the

syntax.

When in a group that is skipped~(\ref{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.

The only white-space characters that shall appear

between preprocessing tokens

within a preprocessing directive

(from just after the introducing

\tcode{\#}

preprocessing token through just before the terminating new-line character)

are space and horizontal-tab

(including spaces that have replaced comments

or possibly other white-space characters

in translation phase 3).

The implementation can

process and skip sections of source files conditionally,

include other source files,

and replace macros.

These capabilities are called

\term{preprocessing},

because conceptually they occur

before translation of the resulting translation unit.

The preprocessing tokens within a preprocessing directive

are not subject to macro expansion unless otherwise stated.

\enterexample 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 \# at the start of

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

has been replaced.\exitexample

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

\indextext{preprocessing directive!conditional inclusion}%

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

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\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.}

and it may contain unary operator expressions of the form

\begin{ncbnf}

\terminal{defined} identifier

\end{ncbnf}

or

\begin{ncbnf}

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

\end{ncbnf}

which evaluate to

\tcode{1}

if the identifier is currently defined

as a macro name

(that is, if it is predefined

or if 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.

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~(\ref{lex.token}).

Preprocessing directives of the forms

\begin{ncbnftab}

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

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

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

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

\end{ncbnftab}

check whether the controlling constant expression evaluates to nonzero.

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 the 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 behavior is undefined.

After all replacements due to macro expansion and the

\tcode{defined}

unary operator have been performed,

all remaining identifiers and keywords\footnote{An alternative

token~(\ref{lex.digraph}) is not an identifier,

even when its spelling consists entirely of letters and underscores.

Therefore it is not subject to this replacement.},

except for

\tcode{true}

and

\tcode{false},

are replaced with the pp-number

\tcode{0},

and then each preprocessing token is converted into a token.

The resulting tokens comprise the controlling constant expression

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

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}~(\ref{cstdint}).\footnote{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~(\ref{lex.phases}).}

This includes interpreting character literals, which may involve

converting escape sequences into execution character set members.

Whether the numeric value for these character literals

matches the value obtained when an identical character literal

occurs in an expression

(other than within a

\tcode{\#if}

or

\tcode{\#elif}

directive)

is \impldef{numeric values of character literals in \tcode{\#if}

directives}.\footnote{Thus, the constant expression in the following

\tcode{\#if}

directive and

\tcode{if}

statement is not guaranteed to evaluate to the same value in these two

contexts.

\begin{tabbing}

\hspace{.6in}\=\kill%

\>\tcode{\#if 'z' - 'a' == 25}\\

\>\tcode{if ('z' - 'a' == 25)}

\end{tabbing}

}

Also, whether a single-character character literal may have a negative

value is \impldef{negative value of character literal in preprocessor}.

Each subexpression with type

\tcode{bool}

is subjected to integral promotion before processing continues.

Preprocessing directives of the forms

\begin{ncbnftab}

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

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

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

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

\end{ncbnftab}

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

Their conditions are equivalent to

\tcode{\#if}

\tcode{defined}

\term{identifier}

and

\tcode{\#if}

\tcode{!defined}

\term{identifier}

respectively.

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.

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.\footnote{As indicated by the syntax,

a preprocessing token shall not follow a

\tcode{\#else}

or

\tcode{\#endif}

directive before the terminating new-line character.

However,

comments may appear anywhere in a source file,

including within a preprocessing directive.}

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

\indextext{preprocessing directives!header inclusion}

\indextext{preprocessing directives!source-file inclusion}

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

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

A

\tcode{\#include}

directive shall identify a header or source file

that can be processed by the implementation.

\indextext{\idxcode{<...>}|see{preprocessing directive, header}}%

A preprocessing directive of the form

\begin{ncsimplebnf}

\terminal{\# include <}h-char-sequence\terminal{>} new-line

\end{ncsimplebnf}

searches a sequence of

\impldef{sequence of places searched for a header}

places

for a header identified uniquely by the specified sequence

between the

\tcode{<}

and

\tcode{>}

delimiters,

and causes the replacement of that

directive by the entire contents of the header.

How the places are specified

or the header identified

is \impldef{search locations for \tcode{<>} header}.

\indextext{\idxcode{\"{}...\"{}}|see{preprocessing directives, source-file inclusion}}%

A preprocessing directive of the form

\begin{ncsimplebnf}

\terminal{\# include "}q-char-sequence\terminal{"} new-line

\end{ncsimplebnf}

causes the replacement of that

directive by the entire contents of the

source file identified by the specified sequence between the

\tcode{"}

delimiters.

The named source file is searched for in an

\impldef{manner of search for included source file}

manner.

If this search is not supported,

or if the search fails,

the directive is reprocessed as if it read

\begin{ncsimplebnf}

\terminal{\# include <}h-char-sequence\terminal{>} new-line

\end{ncsimplebnf}

with the identical contained sequence (including

\tcode{>}

characters, if any) from the original directive.

A preprocessing directive of the form

\begin{ncsimplebnf}

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

\end{ncsimplebnf}

(that does not match one of the two previous forms) 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).

If the directive resulting after all replacements does not match

one of the two previous forms, the behavior is

undefined.\footnote{Note that adjacent string literals are not concatenated into

a single string literal

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

thus, an expansion that results in two string literals is an

invalid directive.}

The method by which a sequence of preprocessing tokens between a

\tcode{<}

and a

\tcode{>}

preprocessing token pair or a pair of

\tcode{"}

characters is combined into a single header name

preprocessing token is \impldef{search locations for \tcode{""""} header}.

The implementation shall provide unique mappings for

sequences consisting of one or more

\grammarterm{nondigit}{s} or \grammarterm{digit}{s}~(\ref{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.

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.

Although an implementation may provide a mechanism for making arbitrary

source files available to the \tcode{< >} search, in general

programmers should use the \tcode{< >} form for headers provided

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

outside the control of the implementation. For instance:

\begin{codeblock}

#include <stdio.h>

#include <unistd.h>

#include "usefullib.h"

#include "myprog.h"

\end{codeblock}

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}

\rSec1[cpp.replace]{Macro replacement}%

\indextext{macro!replacement|(}%

\indextext{replacement!macro|see{macro, replacement}}%

\indextext{preprocessing directives!macro replacement|see{macro, replacement}}

\indextext{macro!replacement list}%

Two replacement lists are identical if and only if

the preprocessing tokens in both have

the same number, ordering, spelling, and white-space separation,

where all white-space separations are considered identical.

An identifier currently defined as an

\indextext{object-like macro|see{macro, object-like}}%

\indextext{macro!object-like}%

\grammarterm{object-like}

macro may be redefined by another

\tcode{\#define}

preprocessing 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

a

\indextext{function-like macro|see{macro, function-like}}%

\indextext{macro!function-like}%

\grammarterm{function-like}

macro may be redefined by another

\tcode{\#define}

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

\indextext{macro!replacement list}%

There shall be white-space between the identifier and the replacement list

in the definition of an object-like macro.

If the \grammarterm{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 more arguments in the invocation than there are

parameters in the macro definition (excluding the \tcode{...}). There

shall exist a

\tcode{)}

preprocessing token that terminates the invocation.

\indextext{\xname{VA_ARGS}@\mname{VA_ARGS}}%

The identifier \mname{VA_ARGS} shall occur only in the replacement-list

of 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 the

\tcode{define}

is called the

\indextext{macro!name}%

\indextext{name!macro|see{macro, name}}%

\term{macro name}.

There is one name space for macro names.

Any white-space 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

\indextext{\#\#0~operator@\tcode{\#}~operator}

\tcode{\#}

preprocessing token,

followed by an identifier,

occurs lexically

at the point at which a preprocessing directive could begin,

the identifier is not subject to macro replacement.

A preprocessing directive of the form

\begin{ncsimplebnf}

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

\indextext{\idxcode{\#define}}%

\end{ncsimplebnf}

defines an

\indextext{macro!object-like}%

\grammarterm{object-like macro} that

causes each subsequent instance of the macro name\footnote{Since, by macro-replacement time,

all character literals and string literals are preprocessing tokens,

not sequences possibly containing identifier-like subsequences

(see \ref{lex.phases}, translation phases),

they are never scanned for macro names or parameters.}

to be replaced by the replacement list of preprocessing tokens

that constitute the remainder of the directive.\footnote{An alternative token~(\ref{lex.digraph}) is not an identifier,

even when its spelling consists entirely of letters and underscores.

Therefore it is not possible to define a macro

whose name is the same as that of an alternative token.}

The replacement list is then rescanned for more macro names as

specified below.

A preprocessing directive of the form

\begin{ncsimplebnf}

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

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

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

\end{ncsimplebnf}

\indextext{macro!function-like}%

defines a \grammarterm{function-like macro}

with parameters, whose use is

similar syntactically to a function call.

The parameters

\indextext{parameters!macro}%

are specified by the optional list of identifiers,

whose scope extends from their declaration in the identifier list

until the new-line character that terminates the

\tcode{\#define}

preprocessing directive.

Each subsequent instance of the function-like macro name followed by a

\tcode{(}

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

\indextext{invocation!macro}%

The replaced sequence of preprocessing tokens is terminated by the matching

\tcode{)}

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 white-space character.

\indextext{macro!function-like!arguments}%

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,\footnote{Despite the name, a non-directive is a preprocessing directive.}

the behavior is undefined.

\indextext{macro!function-like!arguments}%

If there is a \tcode{...} immediately preceding the \tcode{)} in the

function-like macro

definition, then the trailing arguments, including any separating comma preprocessing

tokens, are merged to form a single item: the \term{variable arguments}. The number of

arguments so combined is such that, following merger, the number of arguments is

one more than the number of parameters in the macro definition (excluding the

\tcode{...}).

\rSec2[cpp.subst]{Argument substitution}%

\indextext{macro!argument substitution}%

\indextext{argument~substitution|see{macro, argument substitution}}%

After the arguments for the invocation of a function-like macro have

been identified, argument substitution takes place.

A parameter in the replacement list, unless preceded by a

\tcode{\#}

or

\tcode{\#\#}

preprocessing token or followed by a

\tcode{\#\#}

preprocessing token (see below),

is replaced by the corresponding argument after all macros

contained therein have been expanded.

Before being substituted,

each argument's preprocessing tokens are completely

macro replaced as if they formed the rest of the

preprocessing file;

no other preprocessing tokens are available.

An identifier \mname{VA_ARGS} that occurs in the replacement list

shall be treated as if it were a parameter, and the variable arguments shall form

the preprocessing tokens used to replace it.

\rSec2[cpp.stringize]{The \tcode{\#} operator}%

\indextext{\#\#0~operator@\tcode{\#}~operator}%

\indextext{stringize|see{\tcode{\#}}}

Each

\tcode{\#}

preprocessing token in the replacement list for a function-like

macro shall be followed by a parameter as the next preprocessing

token in the replacement list.

A \defn{character string literal} is a \grammarterm{string-literal} with no prefix.

If, in the replacement list, a parameter is immediately

preceded by a

\tcode{\#}

preprocessing token,

both are replaced by a single character string literal preprocessing token that

contains the spelling of the preprocessing token sequence for the

corresponding argument.

Each occurrence of white space between the argument's preprocessing

tokens becomes a single space character in the character string literal.

White space before the first preprocessing token and after the last

preprocessing token comprising the argument is deleted.

Otherwise, the original spelling of each preprocessing token in the

argument is retained in the character string literal,

except for special handling for producing the spelling of

string literals and character literals:

a

\tcode{\textbackslash}

character is inserted before each

\tcode{"}

and

\tcode{\textbackslash}

character of a character literal or string literal

(including the delimiting

\tcode{"}

characters).

If the replacement that results is not a valid character string literal,

the behavior is undefined. The character string literal corresponding to

an empty argument is \tcode{""}.

The order of evaluation of

\tcode{\#}

and

\tcode{\#\#}

operators is unspecified.

\rSec2[cpp.concat]{The \tcode{\#\#} operator}%

\indextext{\#\#1 operator@\tcode{\#\#} operator}%

\indextext{concatenation!macro argument|see{\tcode{\#\#}}}

A

\tcode{\#\#}

preprocessing token shall not occur at the beginning or

at the end of a replacement list for either form

of macro definition.

If, in the replacement list of a function-like macro, a parameter is

immediately preceded or followed by a

\tcode{\#\#}

preprocessing token, the parameter is replaced by the

corresponding argument's preprocessing token sequence; however, if an argument consists of no preprocessing tokens, the parameter is

replaced by a placemarker preprocessing token instead.\footnote{Placemarker preprocessing tokens do not appear in the syntax

because they are temporary entities that exist only within translation phase 4.}

For both object-like and function-like macro invocations, before the

replacement list is reexamined for more macro names to replace,

each instance of a

\tcode{\#\#}

preprocessing token in the replacement list

(not from an argument) is deleted and the

preceding preprocessing token is concatenated

with the following preprocessing token.

Placemarker preprocessing tokens are handled specially: concatenation

of two placemarkers results in a single placemarker preprocessing token, and

concatenation of a placemarker with a non-placemarker preprocessing token results

in the non-placemarker preprocessing token.

If the result is not a valid preprocessing token,

the behavior is undefined.

The resulting token is available for further macro replacement.

The order of evaluation of

\tcode{\#\#}

operators is unspecified.

\enterexample In the following fragment:

\begin{codeblock}

#define hash_hash # ## #

#define mkstr(a) # a

#define in_between(a) mkstr(a)

#define join(c, d) in_between(c hash_hash d)

char p[] = join(x, y); // equivalent to

// char p[] = "x \#\# y";

\end{codeblock}

The expansion produces, at various stages:

\begin{codeblock}

join(x, y)

in_between(x hash_hash y)

in_between(x ## y)

mkstr(x ## y)

\end{codeblock}

In other words, expanding \tcode{hash_hash} produces a new token,

consisting of two adjacent sharp signs, but this new token is not the

\tcode{\#\#} operator. \exitexample

\rSec2[cpp.rescan]{Rescanning and further replacement}%

\indextext{macro!rescanning and replacement}%

\indextext{rescanning and replacement|see{macro, rescanning and replacement}}

After all parameters in the replacement list have been substituted and \tcode{\#} and \tcode{\#\#} processing has taken

place, all placemarker preprocessing tokens are removed. Then

the resulting preprocessing token sequence is rescanned, along with all

subsequent preprocessing tokens of the source file, for more macro names

to replace.

If the name of the macro being replaced is found during this scan of

the replacement list

(not including the rest of the source file's preprocessing tokens),

it is not replaced.

Furthermore,

if any nested replacements encounter the name of the macro being replaced,

it is not replaced.

These nonreplaced macro name preprocessing tokens are no longer available

for further replacement even if they are later (re)examined in contexts

in which that macro name preprocessing token would otherwise have been

replaced.

The resulting completely macro-replaced preprocessing token sequence

is not processed as a preprocessing directive even if it resembles one,

but all pragma unary operator expressions within it are then processed as

specified in~\ref{cpp.pragma.op} below.

\rSec2[cpp.scope]{Scope of macro definitions}%

\indextext{macro!scope of definition}%

\indextext{scope!macro definition|see{macro, scope of definition}}

A macro definition lasts

(independent of block structure)

until a corresponding

\tcode{\#undef}

directive is encountered or

(if none is encountered)

until the end of the translation unit.

Macro definitions have no significance after translation phase 4.

A preprocessing directive of the form

\begin{ncsimplebnf}

\terminal{\# undef} identifier new-line

\indextext{\idxcode{\#undef}}%

\end{ncsimplebnf}

causes the specified identifier no longer to be defined as a macro name.

It is ignored if the specified identifier is not currently defined as

a macro name.

The simplest use of this facility is to define a ``manifest constant,''

as in

\begin{codeblock}

#define TABSIZE 100

int table[TABSIZE];

\end{codeblock}

The following defines a function-like

macro whose value is the maximum of its arguments.

It has the advantages of working for any compatible types of the arguments

and of generating in-line code without the overhead of function calling.

It has the disadvantages of evaluating one or the other of its arguments

a second time

(including

\indextext{side effects}%

side effects)

and generating more code than a function if invoked several times.

It also cannot have its address taken,

as it has none.

\begin{codeblock}

#define max(a, b) ((a) > (b) ? (a) : (b))

\end{codeblock}

The parentheses ensure that the arguments and

the resulting expression are bound properly.

To illustrate the rules for redefinition and reexamination,

the sequence

\begin{codeblock}

#define x 3

#define f(a) f(x * (a))

#undef x

#define x 2

#define g f

#define z z[0]

#define h g(~

#define m(a) a(w)

#define w 0,1

#define t(a) a

#define p() int

#define q(x) x

#define r(x,y) x ## y

#define str(x) # x

f(y+1) + f(f(z)) % t(t(g)(0) + t)(1);

g(x+(3,4)-w) | h 5) & m

(f)^m(m);

p() i[q()] = { q(1), r(2,3), r(4,), r(,5), r(,) };

char c[2][6] = { str(hello), str() };

\end{codeblock}

results in

\begin{codeblock}

f(2 * (y+1)) + f(2 * (f(2 * (z[0])))) % f(2 * (0)) + t(1);

f(2 * (2+(3,4)-0,1)) | f(2 * (~ 5)) & f(2 * (0,1))^m(0,1);

int i[] = { 1, 23, 4, 5, };

char c[2][6] = { "hello", "" };

\end{codeblock}

To illustrate the rules for creating character string literals

and concatenating tokens,

the sequence

\begin{codeblock}

#define str(s) # s

#define xstr(s) str(s)

#define debug(s, t) printf("x" # s "= %d, x" # t "= %s", @\textbackslash@

x ## s, x ## t)

#define INCFILE(n) vers ## n

#define glue(a, b) a ## b

#define xglue(a, b) glue(a, b)

#define HIGHLOW "hello"

#define LOW LOW ", world"

debug(1, 2);

fputs(str(strncmp("abc@\textbackslash@0d", "abc", '@\textbackslash@4') // this goes away

== 0) str(: @\atsign\textbackslash@n), s);

#include xstr(INCFILE(2).h)

glue(HIGH, LOW);

xglue(HIGH, LOW)

\end{codeblock}

results in

\begin{codeblock}

printf("x" "1" "= %d, x" "2" "= %s", x1, x2);

fputs("strncmp(@\textbackslash@"abc@\textbackslash\textbackslash@0d@\textbackslash@", @\textbackslash@"abc@\textbackslash@", '@\textbackslash\textbackslash@4') == 0" ": @\atsign\textbackslash@n", s);

#include "vers2.h" @\textit{(after macro replacement, before file access)}@

"hello";

"hello" ", world"

\end{codeblock}

or, after concatenation of the character string literals,

\begin{codeblock}

printf("x1= %d, x2= %s", x1, x2);

fputs("strncmp(@\textbackslash@"abc@\textbackslash\textbackslash@0d@\textbackslash@", @\textbackslash@"abc@\textbackslash@", '@\textbackslash\textbackslash@4') == 0: @\atsign\textbackslash@n", s);

#include "vers2.h" @\textit{(after macro replacement, before file access)}@

"hello";

\end{codeblock}

Space around the

\tcode{\#}

and

\tcode{\#\#}

tokens in the macro definition is optional.

To illustrate the rules for placemarker preprocessing tokens, the sequence

\begin{codeblock}

#define t(x,y,z) x ## y ## z

int j[] = { t(1,2,3), t(,4,5), t(6,,7), t(8,9,),

t(10,,), t(,11,), t(,,12), t(,,) };