* Object-like Macros::
* Function-like Macros::
* Macro Arguments::
-* Stringification::
+* Stringizing::
* Concatenation::
* Variadic Macros::
* Predefined Macros::
* Object-like Macros::
* Function-like Macros::
* Macro Arguments::
-* Stringification::
+* Stringizing::
* Concatenation::
* Variadic Macros::
* Predefined Macros::
foo(bar) @expansion{} bar, "x"
@end smallexample
-@node Stringification
-@section Stringification
-@cindex stringification
+@node Stringizing
+@section Stringizing
+@cindex stringizing
@cindex @samp{#} operator
Sometimes you may want to convert a macro argument into a string
parameter is used with a leading @samp{#}, the preprocessor replaces it
with the literal text of the actual argument, converted to a string
constant. Unlike normal parameter replacement, the argument is not
-macro-expanded first. This is called @dfn{stringification}.
+macro-expanded first. This is called @dfn{stringizing}.
There is no way to combine an argument with surrounding text and
-stringify it all together. Instead, you can write a series of adjacent
-string constants and stringified arguments. The preprocessor will
-replace the stringified arguments with string constants. The C
-compiler will then combine all the adjacent string constants into one
+stringize it all together. Instead, you can write a series of adjacent
+string constants and stringized arguments. The preprocessor
+replaces the stringized arguments with string constants. The C
+compiler then combines all the adjacent string constants into one
long string.
-Here is an example of a macro definition that uses stringification:
+Here is an example of a macro definition that uses stringizing:
@smallexample
@group
@noindent
The argument for @code{EXP} is substituted once, as-is, into the
-@code{if} statement, and once, stringified, into the argument to
+@code{if} statement, and once, stringized, into the argument to
@code{fprintf}. If @code{x} were a macro, it would be expanded in the
@code{if} statement, but not in the string.
@code{WARN_IF} to a function would make C programmers want to do; see
@ref{Swallowing the Semicolon}.
-Stringification in C involves more than putting double-quote characters
+Stringizing in C involves more than putting double-quote characters
around the fragment. The preprocessor backslash-escapes the quotes
surrounding embedded string constants, and all backslashes within string and
character constants, in order to get a valid C string constant with the
-proper contents. Thus, stringifying @code{@w{p = "foo\n";}} results in
+proper contents. Thus, stringizing @code{@w{p = "foo\n";}} results in
@t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string
or character constants are not duplicated: @samp{\n} by itself
-stringifies to @t{"\n"}.
+stringizes to @t{"\n"}.
-All leading and trailing whitespace in text being stringified is
+All leading and trailing whitespace in text being stringized is
ignored. Any sequence of whitespace in the middle of the text is
-converted to a single space in the stringified result. Comments are
-replaced by whitespace long before stringification happens, so they
-never appear in stringified text.
+converted to a single space in the stringized result. Comments are
+replaced by whitespace long before stringizing happens, so they
+never appear in stringized text.
There is no way to convert a macro argument into a character constant.
-If you want to stringify the result of expansion of a macro argument,
+If you want to stringize the result of expansion of a macro argument,
you have to use two levels of macros.
@smallexample
@expansion{} "4"
@end smallexample
-@code{s} is stringified when it is used in @code{str}, so it is not
+@code{s} is stringized when it is used in @code{str}, so it is not
macro-expanded first. But @code{s} is an ordinary argument to
@code{xstr}, so it is completely macro-expanded before @code{xstr}
itself is expanded (@pxref{Argument Prescan}). Therefore, by the time
Token pasting is most useful when one or both of the tokens comes from a
macro argument. If either of the tokens next to an @samp{##} is a
parameter name, it is replaced by its actual argument before @samp{##}
-executes. As with stringification, the actual argument is not
+executes. As with stringizing, the actual argument is not
macro-expanded first. If the argument is empty, that @samp{##} has no
effect.
It would be cleaner not to have to give each command name twice, once in
the string constant and once in the function name. A macro which takes the
name of a command as an argument can make this unnecessary. The string
-constant can be created with stringification, and the function name by
+constant can be created with stringizing, and the function name by
concatenating the argument with @samp{_command}. Here is how it is done:
@smallexample
The variable argument is completely macro-expanded before it is inserted
into the macro expansion, just like an ordinary argument. You may use
-the @samp{#} and @samp{##} operators to stringify the variable argument
+the @samp{#} and @samp{##} operators to stringize the variable argument
or to paste its leading or trailing token with another token. (But see
below for an important special case for @samp{##}.)
@cindex prescan of macro arguments
Macro arguments are completely macro-expanded before they are
-substituted into a macro body, unless they are stringified or pasted
+substituted into a macro body, unless they are stringized 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 @emph{twice} to expand
be expanded.
@item
-Macros that call other macros that stringify or concatenate.
+Macros that call other macros that stringize or concatenate.
-If an argument is stringified or concatenated, the prescan does not
-occur. If you @emph{want} to expand a macro, then stringify or
+If an argument is stringized or concatenated, the prescan does not
+occur. If you @emph{want} to expand a macro, then stringize or
concatenate its expansion, you can do that by causing one macro to call
-another macro that does the stringification or concatenation. For
+another macro that does the stringizing or concatenation. For
instance, if you have
@smallexample
replacement text, but it careful to do it in such a way that the
observed effect is identical even in the function-like macro case.)
-The ISO stringification operator @samp{#} and token paste operator
+The ISO stringizing operator @samp{#} and token paste operator
@samp{##} have no special meaning. As explained later, an effect
similar to these operators can be obtained in a different way. Macro
names that are embedded in quotes, either from the main file or after
The C standard also specifies that a new line in the middle of the
arguments to a macro is treated as whitespace. This white space is
-important in case the macro argument is stringified. The state variable
+important in case the macro argument is stringized. The state variable
@code{parsing_args} is nonzero when the preprocessor is collecting the
arguments to a macro call. It is set to 1 when looking for the opening
parenthesis to a function-like macro, and 2 when collecting the actual
remain valid. However, macros are a little trickier than that, since
they give rise to three sources of fresh tokens. They are the built-in
macros like @code{__LINE__}, and the @samp{#} and @samp{##} operators
-for stringification and token pasting. I handled this by allocating
+for stringizing and token pasting. I handled this by allocating
space for these tokens from the lexer's token run chain. This means
they automatically receive the same lifetime guarantees as lexed tokens,
and we don't need to concern ourselves with freeing them.
I strongly recommend you have a good grasp of how the C and C++
standards require macros to be expanded before diving into this
section, let alone the code!. If you don't have a clear mental
-picture of how things like nested macro expansion, stringification and
+picture of how things like nested macro expansion, stringizing and
token pasting are supposed to work, damage to your sanity can quickly
result.
carries source token @samp{foo} with no leading space.
It is vital that cpplib get spacing correct in these examples since any
-of these macro expansions could be stringified, where spacing matters.
+of these macro expansions could be stringized, where spacing matters.
So, this demonstrates that not just entering macro and argument
expansions, but leaving them requires special handling too. I made
projects / gcc.git / commitdiff