aarch64-linux-gnu-5.1/share/doc/cpp/Argument-Prescan.html - toolchains/linux-x86/gcc - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <!-- Copyright (C) 1987-2015 Free Software Foundation, Inc.

 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation.  A copy of
 the license is included in the
 section entitled "GNU Free Documentation License".

 This manual contains no Invariant Sections.  The Front-Cover Texts are
 (a) (see below), and the Back-Cover Texts are (b) (see below).

 (a) The FSF's Front-Cover Text is:

 A GNU Manual

 (b) The FSF's Back-Cover Text is:

 You have freedom to copy and modify this GNU Manual, like GNU
      software.  Copies published by the Free Software Foundation raise
      funds for GNU development. -->
 <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
 <head>
 <title>The C Preprocessor: Argument Prescan</title>

 <meta name="description" content="The C Preprocessor: Argument Prescan">
 <meta name="keywords" content="The C Preprocessor: Argument Prescan">
 <meta name="resource-type" content="document">
 <meta name="distribution" content="global">
 <meta name="Generator" content="makeinfo">
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link href="index.html#Top" rel="start" title="Top">
 <link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives">
 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
 <link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls">
 <link href="Newlines-in-Arguments.html#Newlines-in-Arguments" rel="next" title="Newlines in Arguments">
 <link href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" rel="prev" title="Self-Referential Macros">
 <style type="text/css">
 <!--
 a.summary-letter {text-decoration: none}
 blockquote.smallquotation {font-size: smaller}
 div.display {margin-left: 3.2em}
 div.example {margin-left: 3.2em}
 div.indentedblock {margin-left: 3.2em}
 div.lisp {margin-left: 3.2em}
 div.smalldisplay {margin-left: 3.2em}
 div.smallexample {margin-left: 3.2em}
 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
 div.smalllisp {margin-left: 3.2em}
 kbd {font-style:oblique}
 pre.display {font-family: inherit}
 pre.format {font-family: inherit}
 pre.menu-comment {font-family: serif}
 pre.menu-preformatted {font-family: serif}
 pre.smalldisplay {font-family: inherit; font-size: smaller}
 pre.smallexample {font-size: smaller}
 pre.smallformat {font-family: inherit; font-size: smaller}
 pre.smalllisp {font-size: smaller}
 span.nocodebreak {white-space:nowrap}
 span.nolinebreak {white-space:nowrap}
 span.roman {font-family:serif; font-weight:normal}
 span.sansserif {font-family:sans-serif; font-weight:normal}
 ul.no-bullet {list-style: none}
 -->
 </style>


 </head>

 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
 <a name="Argument-Prescan"></a>
 <div class="header">
 <p>
 Next: <a href="Newlines-in-Arguments.html#Newlines-in-Arguments" accesskey="n" rel="next">Newlines in Arguments</a>, Previous: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="p" rel="prev">Self-Referential Macros</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
 </div>
 <hr>
 <a name="Argument-Prescan-1"></a>
 <h4 class="subsection">3.10.6 Argument Prescan</h4>
 <a name="index-expansion-of-arguments"></a>
 <a name="index-macro-argument-expansion"></a>
 <a name="index-prescan-of-macro-arguments"></a>

 <p>Macro arguments are completely macro-expanded before they are
 substituted into a macro body, unless they are stringified or pasted
 with other tokens.  After substitution, the entire macro body, including
 the substituted arguments, is scanned again for macros to be expanded.
 The result is that the arguments are scanned <em>twice</em> to expand
 macro calls in them.
 </p>
 <p>Most of the time, this has no effect.  If the argument contained any
 macro calls, they are expanded during the first scan.  The result
 therefore contains no macro calls, so the second scan does not change
 it.  If the argument were substituted as given, with no prescan, the
 single remaining scan would find the same macro calls and produce the
 same results.
 </p>
 <p>You might expect the double scan to change the results when a
 self-referential macro is used in an argument of another macro
 (see <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">Self-Referential Macros</a>): the self-referential macro would be
 expanded once in the first scan, and a second time in the second scan.
 However, this is not what happens.  The self-references that do not
 expand in the first scan are marked so that they will not expand in the
 second scan either.
 </p>
 <p>You might wonder, &ldquo;Why mention the prescan, if it makes no difference?
 And why not skip it and make the preprocessor faster?&rdquo;  The answer is
 that the prescan does make a difference in three special cases:
 </p>
 <ul>
 <li> Nested calls to a macro.

 <p>We say that <em>nested</em> calls to a macro occur when a macro&rsquo;s argument
 contains a call to that very macro.  For example, if <code>f</code> is a macro
 that expects one argument, <code>f (f (1))</code> is a nested pair of calls to
 <code>f</code>.  The desired expansion is made by expanding <code>f (1)</code> and
 substituting that into the definition of <code>f</code>.  The prescan causes
 the expected result to happen.  Without the prescan, <code>f (1)</code> itself
 would be substituted as an argument, and the inner use of <code>f</code> would
 appear during the main scan as an indirect self-reference and would not
 be expanded.
 </p>
 </li><li> Macros that call other macros that stringify or concatenate.

 <p>If an argument is stringified or concatenated, the prescan does not
 occur.  If you <em>want</em> to expand a macro, then stringify or
 concatenate its expansion, you can do that by causing one macro to call
 another macro that does the stringification or concatenation.  For
 instance, if you have
 </p>
 <div class="smallexample">
 <pre class="smallexample">#define AFTERX(x) X_ ## x
 #define XAFTERX(x) AFTERX(x)
 #define TABLESIZE 1024
 #define BUFSIZE TABLESIZE
 </pre></div>

 <p>then <code>AFTERX(BUFSIZE)</code> expands to <code>X_BUFSIZE</code>, and
 <code>XAFTERX(BUFSIZE)</code> expands to <code>X_1024</code>.  (Not to
 <code>X_TABLESIZE</code>.  Prescan always does a complete expansion.)
 </p>
 </li><li> Macros used in arguments, whose expansions contain unshielded commas.

 <p>This can cause a macro expanded on the second scan to be called with the
 wrong number of arguments.  Here is an example:
 </p>
 <div class="smallexample">
 <pre class="smallexample">#define foo  a,b
 #define bar(x) lose(x)
 #define lose(x) (1 + (x))
 </pre></div>

 <p>We would like <code>bar(foo)</code> to turn into <code>(1 + (foo))</code>, which
 would then turn into <code>(1 + (a,b))</code>.  Instead, <code>bar(foo)</code>
 expands into <code>lose(a,b)</code>, and you get an error because <code>lose</code>
 requires a single argument.  In this case, the problem is easily solved
 by the same parentheses that ought to be used to prevent misnesting of
 arithmetic operations:
 </p>
 <div class="smallexample">
 <pre class="smallexample">#define foo (a,b)
 </pre><pre class="smallexample">or
 </pre><pre class="smallexample">#define bar(x) lose((x))
 </pre></div>

 <p>The extra pair of parentheses prevents the comma in <code>foo</code>&rsquo;s
 definition from being interpreted as an argument separator.
 </p>
 </li></ul>

 <hr>
 <div class="header">
 <p>
 Next: <a href="Newlines-in-Arguments.html#Newlines-in-Arguments" accesskey="n" rel="next">Newlines in Arguments</a>, Previous: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="p" rel="prev">Self-Referential Macros</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
 </div>


 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<!-- Copyright (C) 1987-2015 Free Software Foundation, Inc.

	Permission is granted to copy, distribute and/or modify this document
	under the terms of the GNU Free Documentation License, Version 1.3 or
	any later version published by the Free Software Foundation. A copy of
	the license is included in the
	section entitled "GNU Free Documentation License".

	This manual contains no Invariant Sections. The Front-Cover Texts are
	(a) (see below), and the Back-Cover Texts are (b) (see below).

	(a) The FSF's Front-Cover Text is:

	A GNU Manual

	(b) The FSF's Back-Cover Text is:

	You have freedom to copy and modify this GNU Manual, like GNU
	software. Copies published by the Free Software Foundation raise
	funds for GNU development. -->
	<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
	<head>
	<title>The C Preprocessor: Argument Prescan</title>

	<meta name="description" content="The C Preprocessor: Argument Prescan">
	<meta name="keywords" content="The C Preprocessor: Argument Prescan">
	<meta name="resource-type" content="document">
	<meta name="distribution" content="global">
	<meta name="Generator" content="makeinfo">
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<link href="index.html#Top" rel="start" title="Top">
	<link href="Index-of-Directives.html#Index-of-Directives" rel="index" title="Index of Directives">
	<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
	<link href="Macro-Pitfalls.html#Macro-Pitfalls" rel="up" title="Macro Pitfalls">
	<link href="Newlines-in-Arguments.html#Newlines-in-Arguments" rel="next" title="Newlines in Arguments">
	<link href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" rel="prev" title="Self-Referential Macros">
	<style type="text/css">
	<!--
	a.summary-letter {text-decoration: none}
	blockquote.smallquotation {font-size: smaller}
	div.display {margin-left: 3.2em}
	div.example {margin-left: 3.2em}
	div.indentedblock {margin-left: 3.2em}
	div.lisp {margin-left: 3.2em}
	div.smalldisplay {margin-left: 3.2em}
	div.smallexample {margin-left: 3.2em}
	div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
	div.smalllisp {margin-left: 3.2em}
	kbd {font-style:oblique}
	pre.display {font-family: inherit}
	pre.format {font-family: inherit}
	pre.menu-comment {font-family: serif}
	pre.menu-preformatted {font-family: serif}
	pre.smalldisplay {font-family: inherit; font-size: smaller}
	pre.smallexample {font-size: smaller}
	pre.smallformat {font-family: inherit; font-size: smaller}
	pre.smalllisp {font-size: smaller}
	span.nocodebreak {white-space:nowrap}
	span.nolinebreak {white-space:nowrap}
	span.roman {font-family:serif; font-weight:normal}
	span.sansserif {font-family:sans-serif; font-weight:normal}
	ul.no-bullet {list-style: none}
	-->
	</style>


	</head>

	<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
	<a name="Argument-Prescan"></a>
	<div class="header">
	<p>
	Next: <a href="Newlines-in-Arguments.html#Newlines-in-Arguments" accesskey="n" rel="next">Newlines in Arguments</a>, Previous: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="p" rel="prev">Self-Referential Macros</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a>   [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
	</div>
	<hr>
	<a name="Argument-Prescan-1"></a>
	<h4 class="subsection">3.10.6 Argument Prescan</h4>
	<a name="index-expansion-of-arguments"></a>
	<a name="index-macro-argument-expansion"></a>
	<a name="index-prescan-of-macro-arguments"></a>

	<p>Macro arguments are completely macro-expanded before they are
	substituted into a macro body, unless they are stringified or pasted
	with other tokens. After substitution, the entire macro body, including
	the substituted arguments, is scanned again for macros to be expanded.
	The result is that the arguments are scanned <em>twice</em> to expand
	macro calls in them.
	</p>
	<p>Most of the time, this has no effect. If the argument contained any
	macro calls, they are expanded during the first scan. The result
	therefore contains no macro calls, so the second scan does not change
	it. If the argument were substituted as given, with no prescan, the
	single remaining scan would find the same macro calls and produce the
	same results.
	</p>
	<p>You might expect the double scan to change the results when a
	self-referential macro is used in an argument of another macro
	(see <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">Self-Referential Macros</a>): the self-referential macro would be
	expanded once in the first scan, and a second time in the second scan.
	However, this is not what happens. The self-references that do not
	expand in the first scan are marked so that they will not expand in the
	second scan either.
	</p>
	<p>You might wonder, “Why mention the prescan, if it makes no difference?
	And why not skip it and make the preprocessor faster?” The answer is
	that the prescan does make a difference in three special cases:
	</p>
	<ul>
	<li> Nested calls to a macro.

	<p>We say that <em>nested</em> calls to a macro occur when a macro’s argument
	contains a call to that very macro. For example, if <code>f</code> is a macro
	that expects one argument, <code>f (f (1))</code> is a nested pair of calls to
	<code>f</code>. The desired expansion is made by expanding <code>f (1)</code> and
	substituting that into the definition of <code>f</code>. The prescan causes
	the expected result to happen. Without the prescan, <code>f (1)</code> itself
	would be substituted as an argument, and the inner use of <code>f</code> would
	appear during the main scan as an indirect self-reference and would not
	be expanded.
	</p>
	</li><li> Macros that call other macros that stringify or concatenate.

	<p>If an argument is stringified or concatenated, the prescan does not
	occur. If you <em>want</em> to expand a macro, then stringify or
	concatenate its expansion, you can do that by causing one macro to call
	another macro that does the stringification or concatenation. For
	instance, if you have
	</p>
	<div class="smallexample">
	<pre class="smallexample">#define AFTERX(x) X_ ## x
	#define XAFTERX(x) AFTERX(x)
	#define TABLESIZE 1024
	#define BUFSIZE TABLESIZE
	</pre></div>

	<p>then <code>AFTERX(BUFSIZE)</code> expands to <code>X_BUFSIZE</code>, and
	<code>XAFTERX(BUFSIZE)</code> expands to <code>X_1024</code>. (Not to
	<code>X_TABLESIZE</code>. Prescan always does a complete expansion.)
	</p>
	</li><li> Macros used in arguments, whose expansions contain unshielded commas.

	<p>This can cause a macro expanded on the second scan to be called with the
	wrong number of arguments. Here is an example:
	</p>
	<div class="smallexample">
	<pre class="smallexample">#define foo a,b
	#define bar(x) lose(x)
	#define lose(x) (1 + (x))
	</pre></div>

	<p>We would like <code>bar(foo)</code> to turn into <code>(1 + (foo))</code>, which
	would then turn into <code>(1 + (a,b))</code>. Instead, <code>bar(foo)</code>
	expands into <code>lose(a,b)</code>, and you get an error because <code>lose</code>
	requires a single argument. In this case, the problem is easily solved
	by the same parentheses that ought to be used to prevent misnesting of
	arithmetic operations:
	</p>
	<div class="smallexample">
	<pre class="smallexample">#define foo (a,b)
	</pre><pre class="smallexample">or
	</pre><pre class="smallexample">#define bar(x) lose((x))
	</pre></div>

	<p>The extra pair of parentheses prevents the comma in <code>foo</code>’s
	definition from being interpreted as an argument separator.
	</p>
	</li></ul>

	<hr>
	<div class="header">
	<p>
	Next: <a href="Newlines-in-Arguments.html#Newlines-in-Arguments" accesskey="n" rel="next">Newlines in Arguments</a>, Previous: <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros" accesskey="p" rel="prev">Self-Referential Macros</a>, Up: <a href="Macro-Pitfalls.html#Macro-Pitfalls" accesskey="u" rel="up">Macro Pitfalls</a>   [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index-of-Directives.html#Index-of-Directives" title="Index" rel="index">Index</a>]</p>
	</div>



	</body>
	</html>