path: root/devdocs/c/preprocessor%2Freplace.html

    <h1 id="firstHeading" class="firstHeading">Replacing text macros</h1>            <p>The preprocessor supports text macro replacement and function-like text macro replacement.</p>
<h3 id="Syntax"> Syntax</h3> <table class="t-sdsc-begin">  <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <span class="t-spar">replacement-list</span> <span class="t-mark">(optional)</span> </td> <td> (1) </td> <td class="t-sdsc-nopad"> </td>
</tr>  <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <code>(</code> <span class="t-spar">parameters</span> <code>)</code> <span class="t-spar">replacement-list</span> </td> <td> (2) </td> <td class="t-sdsc-nopad"> </td>
</tr>  <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <code>(</code> <span class="t-spar">parameters</span><code>, ... )</code> <span class="t-spar">replacement-list</span> </td> <td> (3) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td>
</tr>  <tr class="t-sdsc"> <td> <code>#define</code> <span class="t-spar">identifier</span> <code>( ... )</code> <span class="t-spar">replacement-list</span> </td> <td> (4) </td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td>
</tr>  <tr class="t-sdsc"> <td> <code>#undef</code> <span class="t-spar">identifier</span> </td> <td> (5) </td> <td class="t-sdsc-nopad"> </td>
</tr> 
</table> <h3 id="Explanation"> Explanation</h3> <h4 id=".23define_directives"> <span class="co2">#define</span> directives</h4> <p>The <code>#define</code> directives define the <span class="t-spar">identifier</span> as a macro, that is they instruct the compiler to replace all successive occurrences of <span class="t-spar">identifier</span> with <span class="t-spar">replacement-list</span>, which can be optionally additionally processed. If the identifier is already defined as any type of macro, the program is ill-formed unless the definitions are identical.</p>
<h5 id="Object-like_macros"> Object-like macros</h5> <p>Object-like macros replace every occurrence of a defined <span class="t-spar">identifier</span> with <span class="t-spar">replacement-list</span>. Version (1) of the <code>#define</code> directive behaves exactly like that.</p>
<h5 id="Function-like_macros"> Function-like macros</h5> <p>Function-like macros replace each occurrence of a defined <span class="t-spar">identifier</span> with <span class="t-spar">replacement-list</span>, additionally taking a number of arguments, which then replace corresponding occurrences of any of the <span class="t-spar">parameters</span> in the <span class="t-spar">replacement-list</span>.</p>
<p>The syntax of a function-like macro invocation is similar to the syntax of a function call: each instance of the macro name followed by a ( as the next preprocessing token introduces the sequence of tokens that is replaced by the replacement-list. The sequence is terminated by the matching ) token, skipping intervening matched pairs of left and right parentheses.</p>
<p>The number of arguments must be the same as the number of arguments in the macro definition (<span class="t-spar">parameters</span>) or the program is ill-formed. If the identifier is not in functional-notation, i.e. does not have parentheses after itself, it is not replaced at all.</p>
<p>Version (2) of the <code>#define</code> directive defines a simple function-like macro.</p>
<p>Version (3) of the <code>#define</code> directive defines a function-like macro with variable number of arguments. The additional arguments can be accessed using <code>__VA_ARGS__</code> identifier, which is then replaced with arguments, supplied with the identifier to be replaced.</p>
<p>Version (4) of the <code>#define</code> directive defines a function-like macro with variable number of arguments, but no regular arguments. The arguments can be accessed only with <code>__VA_ARGS__</code> identifier, which is then replaced with arguments, supplied with identifier to be replaced.</p>
<table class="t-rev-begin"> <tr class="t-rev t-since-c23">
<td> <p>For versions (3,4), <span class="t-spar">replacement-list</span> may contain the token sequence <code>__VA_OPT__ (</code> <span class="t-spar">content</span> <code>)</code>, which is replaced by <span class="t-spar">content</span> if <code>__VA_ARGS__</code> is non-empty, and expands to nothing otherwise.</p>
<div class="c source-c"><pre data-language="c">#define F(...) f(0 __VA_OPT__(,) __VA_ARGS__)
F(a, b, c) // replaced by f(0, a, b, c)
F()        // replaced by f(0)
 
#define G(X, ...) f(0, X __VA_OPT__(,) __VA_ARGS__)
G(a, b, c) // replaced by f(0, a, b, c)
G(a, )     // replaced by f(0, a)
G(a)       // replaced by f(0, a)
 
#define SDEF(sname, ...) S sname __VA_OPT__(= { __VA_ARGS__ })
SDEF(foo);       // replaced by S foo;
SDEF(bar, 1, 2); // replaced by S bar = { 1, 2 };</pre></div> </td> <td><span class="t-mark-rev t-since-c23">(since C23)</span></td>
</tr> </table> <p><br> Note: if an argument of a function-like macro includes commas that are not protected by matched pairs of left and right parentheses (such as <code>macro(array[x = y, x + 1])</code> or <code><a href="http://en.cppreference.com/w/c/atomic/atomic_store"><span class="kw937">atomic_store</span></a> <span class="br0">(</span>p, <span class="br0">(</span><span class="kw1">struct</span> S<span class="br0">)</span><span class="br0">{</span> a, b <span class="br0">}</span><span class="br0">)</span><span class="sy4">;</span></code>), the comma is interpreted as macro argument separator, causing a compilation failure due to argument count mismatch.</p>
<h4 id=".23_and_.23.23_operators"> <span class="co2">#</span> and <span class="co2">##</span> operators</h4> <p>In function-like macros, a <code>#</code> operator before an identifier in the <span class="t-spar">replacement-list</span> runs the identifier through parameter replacement and encloses the result in quotes, effectively creating a string literal. In addition, the preprocessor adds backslashes to escape the quotes surrounding embedded string literals, if any, and doubles the backslashes within the string as necessary. All leading and trailing whitespace is removed, and any sequence of whitespace in the middle of the text (but not inside embedded string literals) is collapsed to a single space. This operation is called "stringification". If the result of stringification is not a valid string literal, the behavior is undefined.</p>
<table class="t-rev-begin"> <tr class="t-rev t-since-c99">
<td> <p>When <code>#</code> appears before <code>__VA_ARGS__</code>, the entire expanded <code>__VA_ARGS__</code> is enclosed in quotes:</p>
<div class="c source-c"><pre data-language="c">#define showlist(...) puts(#__VA_ARGS__)
showlist();            // expands to puts("")
showlist(1, "x", int); // expands to puts("1, \"x\", int")</pre></div> </td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td>
</tr> </table> <p>A <code>##</code> operator between any two successive identifiers in the <span class="t-spar">replacement-list</span> runs parameter replacement on the two identifiers and then concatenates the result. This operation is called "concatenation" or "token pasting". Only tokens that form a valid token together may be pasted: identifiers that form a longer identifier, digits that form a number, or operators <code>+</code> and <code>=</code> that form a <code>+=</code>. A comment cannot be created by pasting <code>/</code> and <code>*</code> because comments are removed from text before macro substitution is considered. If the result of concatenation is not a valid token, the behavior is undefined.</p>
<p>Note: Some compilers offer an extension that allows <code>##</code> to appear after a comma and before <code>__VA_ARGS__</code>, in which case the <code>##</code> does nothing when <code>__VA_ARGS__</code> is non-empty, but removes the comma when <code>__VA_ARGS__</code> is empty: this makes it possible to define macros such as <code><a href="http://en.cppreference.com/w/c/io/fprintf"><span class="kw852">fprintf</span></a> <span class="br0">(</span><a href="http://en.cppreference.com/w/c/io/std_streams"><span class="kw888">stderr</span></a>, format, <span class="co2">##__VA_ARGS__)</span></code>.</p>
<p>The order of evaluation of <code>#</code> and <code>##</code> operators is unspecified.</p>
<h4 id=".23undef_directive"> <span class="co2">#undef</span> directive</h4> <p>The <code>#undef</code> directive undefines the <span class="t-spar">identifier</span>, that is it cancels the previous definition of the <span class="t-spar">identifier</span> by <code>#define</code> directive. If the identifier does not have an associated macro, the directive is ignored.</p>
<h3 id="Predefined_macros"> Predefined macros</h3> <p>The following macro names are predefined in any translation unit:</p>
<table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC__</span></span></div> </td> <td> expands to the integer constant <code>1</code>. This macro is intended to indicate a conforming implementation <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_VERSION__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c95">(C95)</span></span></span></div> </td> <td> expands to an integer constant of type <code>long</code> whose value increases with each version of the C standard: <ul>
<li> <code>199409L</code> <span class="t-mark-rev t-since-c95">(C95)</span> </li>
<li> <code>199901L</code> <span class="t-mark-rev t-since-c99">(C99)</span> </li>
<li> <code>201112L</code> <span class="t-mark-rev t-since-c11">(C11)</span> </li>
<li> <code>201710L</code> <span class="t-mark-rev t-since-c17">(C17)</span> </li>
<li> <code>202311L</code> <span class="t-mark-rev t-since-c23">(C23)</span> <br> <span class="t-mark">(macro constant)</span> </li>
</ul> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_HOSTED__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to the integer constant <code>1</code> if the implementation is hosted (runs under an OS), <code>​0​</code> if freestanding (runs without an OS) <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__FILE__</span></span></div> </td> <td> expands to the name of the current file, as a character string literal, can be changed by the <a href="line" title="c/preprocessor/line">#line</a> directive <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__LINE__</span></span></div> </td> <td> expands to the source file line number, an integer constant, can be changed by the <a href="line" title="c/preprocessor/line">#line</a> directive <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__DATE__</span></span></div> </td> <td> expands to the date of translation, a character string literal of the form "Mmm dd yyyy". The name of the month is as if generated by <code><a href="../chrono/asctime" title="c/chrono/asctime">asctime</a></code> and the first character of "dd" is a space if the day of the month is less than 10 <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__TIME__</span></span></div> </td> <td> expands to the time of translation, a character string literal of the form "hh:mm:ss", as in the time generated by <code><a href="http://en.cppreference.com/w/c/chrono/asctime"><span class="kw515">asctime</span></a><span class="br0">(</span><span class="br0">)</span></code> <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_16__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>1</code> to indicate that <code>char16_t</code> use UTF-16 encoding <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_32__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>1</code> to indicate that <code>char32_t</code> use UTF-32 encoding <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_EMBED_NOT_FOUND__</span><span>__STDC_EMBED_FOUND__</span><span>__STDC_EMBED_EMPTY__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expand to <code>​0​</code>, <code>1</code>, and <code>2</code>, respectively <br> <span class="t-mark">(macro constant)</span> </td>
</tr> </table> <p>The following additional macro names may be predefined by an implementation:</p>
<table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_ISO_10646__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to an integer constant of the form <code>yyyymmL</code>, if <code>wchar_t</code> uses Unicode; the date indicates the latest revision of Unicode supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_559__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to <code>1</code> if IEC 60559 is supported <span class="t-rev-inl t-since-c23"><span><span class="t-mark">(deprecated)</span></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_559_COMPLEX__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to <code>1</code> if IEC 60559 complex arithmetic is supported <span class="t-rev-inl t-since-c23"><span><span class="t-mark">(deprecated)</span></span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_16__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <code>char16_t</code> use UTF-16 encoding <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_UTF_32__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <code>char32_t</code> use UTF-32 encoding <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_MB_MIGHT_NEQ_WC__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c99">(C99)</span></span></span></div> </td> <td> expands to <code>1</code> if <code>'x' == L'x'</code> might be false for a member of the basic character set, such as on EBCDIC-based systems that use Unicode for <code>wchar_t</code> <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_ANALYZABLE__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/analyzability" title="c/language/analyzability">analyzability</a> is supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_LIB_EXT1__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to an integer constant <code>201112L</code> if <a href="../error" title="c/error">bounds-checking interfaces</a> are supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_ATOMICS__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/atomic" title="c/language/atomic">atomic</a> types and <a href="../thread#Atomic_operations" title="c/thread">atomic operations library</a> are not supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_COMPLEX__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/arithmetic_types#Complex_floating_types" title="c/language/arithmetic types">complex types</a> and <a href="../numeric/complex" title="c/numeric/complex">complex math library</a> are not supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_THREADS__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../thread" title="c/thread">multithreading</a> is not supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_NO_VLA__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> expands to <code>1</code> if <a href="../language/array#Variable-length_arrays" title="c/language/array">variable-length arrays</a> <span class="t-rev-inl t-until-c23"><span>and variably-modified types</span><span><span class="t-mark-rev t-until-c23">(until C23)</span></span></span><span class="t-rev-inl t-since-c23"><span>of automatic storage duration</span><span><span class="t-mark-rev t-since-c23">(since C23)</span></span></span> are not supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_BFP__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 binary floating-point arithmetic is supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_DFP__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 decimal floating-point arithmetic is supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_COMPLEX__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 complex arithmetic is supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> <tr class="t-dsc"> <td> <div><span class="t-lines"><span>__STDC_IEC_60559_TYPES__</span></span></div>
<div><span class="t-lines"><span><span class="t-mark-rev t-since-c23">(C23)</span></span></span></div> </td> <td> expands to <code>202311L</code> if IEC 60559 interchange and extended types are supported <br> <span class="t-mark">(macro constant)</span> </td>
</tr> </table> <p>The values of these macros (except for <code>__FILE__</code> and <code>__LINE__</code>) remain constant throughout the translation unit. Attempts to redefine or undefine these macros result in undefined behavior.</p>
<table class="t-rev-begin"> <tr class="t-rev t-since-c99">
<td> <p>The predefined variable <code>__func__</code> (see <a href="../language/function_definition#func" title="c/language/function definition">function definition</a> for details) is not a preprocessor macro, even though it is sometimes used together with <code>__FILE__</code> and <code>__LINE__</code>, e.g. by <code><a href="../error/assert" title="c/error/assert">assert</a></code>.</p>
</td> <td><span class="t-mark-rev t-since-c99">(since C99)</span></td>
</tr> </table> <h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include &lt;stdio.h&gt;
 
// make function factory and use it
#define FUNCTION(name, a) int fun_##name(int x) { return (a) * x; }
 
FUNCTION(quadruple, 4)
FUNCTION(double, 2)
 
#undef FUNCTION
#define FUNCTION 34
#define OUTPUT(a) puts( #a )
 
int main(void)
{
    printf("quadruple(13): %d\n", fun_quadruple(13) );
    printf("double(21): %d\n", fun_double(21) );
    printf("%d\n", FUNCTION);
    OUTPUT(billion);               // note the lack of quotes
}</pre></div> <p>Output:</p>
<div class="text source-text"><pre data-language="c">quadruple(13): 52
double(21): 42
34
billion</pre></div> </div> <h3 id="Defect_reports"> Defect reports</h3> <p>The following behavior-changing defect reports were applied retroactively to previously published C standards.</p>
<table class="dsctable"> <tr> <th>DR </th> <th>Applied to </th> <th>Behavior as published </th> <th>Correct behavior </th>
</tr> <tr> <td>
<a rel="nofollow" class="external text" href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/dr_321.htm">DR 321</a> </td> <td>C99 </td> <td>it was unclear if <code>L'x' == 'x'</code> always holds<br>among the basic character set </td> <td>
<code>__STDC_MB_MIGHT_NEQ_WC__</code> added for the purpose </td>
</tr>
</table> <h3 id="References"> References</h3>  <ul>
<li> C23 standard (ISO/IEC 9899:2023): </li>
<ul>
<li> 6.10.4 Macro replacement (p: 187-184) </li>
<li> 6.10.9 Predefined macro names (p: 186-188) </li>
</ul>
<li> C17 standard (ISO/IEC 9899:2018): </li>
<ul>
<li> 6.10.3 Macro replacement (p: 121-126) </li>
<li> 6.10.8 Predefined macro names (p: 127-129) </li>
</ul>
<li> C11 standard (ISO/IEC 9899:2011): </li>
<ul>
<li> 6.10.3 Macro replacement (p: 166-173) </li>
<li> 6.10.8 Predefined macro names (p: 175-176) </li>
</ul>
<li> C99 standard (ISO/IEC 9899:1999): </li>
<ul>
<li> 6.10.3 Macro replacement (p: 151-158) </li>
<li> 6.10.8 Predefined macro names (p: 160-161) </li>
</ul>
<li> C89/C90 standard (ISO/IEC 9899:1990): </li>
<ul>
<li> 3.8.3 Macro replacement </li>
<li> 3.8.8 Predefined macro names </li>
</ul>
</ul>                        <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/preprocessor/replace" title="cpp/preprocessor/replace">C++ documentation</a></span> for <span class=""><span>Replacing text macros</span></span> </td>
</tr> </table>           <div class="_attribution">
  <p class="_attribution-p">
    &copy; cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br>
    <a href="https://en.cppreference.com/w/c/preprocessor/replace" class="_attribution-link">https://en.cppreference.com/w/c/preprocessor/replace</a>
  </p>
</div>