diff options
Diffstat (limited to 'share/doc/cpp/Variadic-Macros.html')
| -rw-r--r-- | share/doc/cpp/Variadic-Macros.html | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/share/doc/cpp/Variadic-Macros.html b/share/doc/cpp/Variadic-Macros.html new file mode 100644 index 0000000..eaa454c --- /dev/null +++ b/share/doc/cpp/Variadic-Macros.html @@ -0,0 +1,223 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1987-2023 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.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>The C Preprocessor: Variadic Macros</title> + +<meta name="description" content="The C Preprocessor: Variadic Macros"> +<meta name="keywords" content="The C Preprocessor: Variadic Macros"> +<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="Macros.html#Macros" rel="up" title="Macros"> +<link href="Predefined-Macros.html#Predefined-Macros" rel="next" title="Predefined Macros"> +<link href="Concatenation.html#Concatenation" rel="previous" title="Concatenation"> +<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="Variadic-Macros"></a> +<div class="header"> +<p> +Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="previous">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</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="Variadic-Macros-1"></a> +<h3 class="section">3.6 Variadic Macros</h3> +<a name="index-variable-number-of-arguments"></a> +<a name="index-macros-with-variable-arguments"></a> +<a name="index-variadic-macros"></a> + +<p>A macro can be declared to accept a variable number of arguments much as +a function can. The syntax for defining the macro is similar to that of +a function. Here is an example: +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(...) fprintf (stderr, __VA_ARGS__) +</pre></div> + +<p>This kind of macro is called <em>variadic</em>. When the macro is invoked, +all the tokens in its argument list after the last named argument (this +macro has none), including any commas, become the <em>variable +argument</em>. This sequence of tokens replaces the identifier +<code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> in the macro body wherever it appears. Thus, we +have this expansion: +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf ("%s:%d: ", input_file, lineno) + → fprintf (stderr, "%s:%d: ", input_file, lineno) +</pre></div> + +<p>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>#</samp>’ and ‘<samp>##</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>##</samp>’.) +</p> +<p>If your macro is complicated, you may want a more descriptive name for +the variable argument than <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>. CPP permits +this, as an extension. You may write an argument name immediately +before the ‘<samp>...</samp>’; that name is used for the variable argument. +The <code>eprintf</code> macro above could be written +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(args...) fprintf (stderr, args) +</pre></div> + +<p>using this extension. You cannot use <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> and this +extension in the same macro. +</p> +<p>You can have named arguments as well as variable arguments in a variadic +macro. We could define <code>eprintf</code> like this, instead: +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) +</pre></div> + +<p>This formulation looks more descriptive, but historically it was less +flexible: you had to supply at least one argument after the format +string. In standard C, you could not omit the comma separating the +named argument from the variable arguments. (Note that this +restriction has been lifted in C++20, and never existed in GNU C; see +below.) +</p> +<p>Furthermore, if you left the variable argument empty, you would have +gotten a syntax error, because there would have been an extra comma +after the format string. +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf("success!\n", ); + → fprintf(stderr, "success!\n", ); +</pre></div> + +<p>This has been fixed in C++20, and GNU CPP also has a pair of +extensions which deal with this problem. +</p> +<p>First, in GNU CPP, and in C++ beginning in C++20, you are allowed to +leave the variable argument out entirely: +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf ("success!\n") + → fprintf(stderr, "success!\n", ); +</pre></div> + +<p>Second, C++20 introduces the <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> function macro. +This macro may only appear in the definition of a variadic macro. If +the variable argument has any tokens, then a <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> +invocation expands to its argument; but if the variable argument does +not have any tokens, the <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> expands to nothing: +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(format, ...) \ + fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__) +</pre></div> + +<p><code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> is also available in GNU C and GNU C++. +</p> +<p>Historically, GNU CPP has also had another extension to handle the +trailing comma: the ‘<samp>##</samp>’ token paste operator has a special +meaning when placed between a comma and a variable argument. Despite +the introduction of <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code>, this extension remains +supported in GNU CPP, for backward compatibility. If you write +</p> +<div class="smallexample"> +<pre class="smallexample">#define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) +</pre></div> + +<p>and the variable argument is left out when the <code>eprintf</code> macro is +used, then the comma before the ‘<samp>##</samp>’ will be deleted. This does +<em>not</em> happen if you pass an empty argument, nor does it happen if +the token preceding ‘<samp>##</samp>’ is anything other than a comma. +</p> +<div class="smallexample"> +<pre class="smallexample">eprintf ("success!\n") + → fprintf(stderr, "success!\n"); +</pre></div> + +<p>The above explanation is ambiguous about the case where the only macro +parameter is a variable arguments parameter, as it is meaningless to +try to distinguish whether no argument at all is an empty argument or +a missing argument. +CPP retains the comma when conforming to a specific C +standard. Otherwise the comma is dropped as an extension to the standard. +</p> +<p>The C standard +mandates that the only place the identifier <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code> +can appear is in the replacement list of a variadic macro. It may not +be used as a macro name, macro argument name, or within a different type +of macro. It may also be forbidden in open text; the standard is +ambiguous. We recommend you avoid using it except for its defined +purpose. +</p> +<p>Likewise, C++ forbids <code><span class="nolinebreak">__VA_OPT__</span><!-- /@w --></code> anywhere outside the +replacement list of a variadic macro. +</p> +<p>Variadic macros became a standard part of the C language with C99. +GNU CPP previously supported them +with a named variable argument +(‘<samp>args...</samp>’, not ‘<samp>...</samp>’ and <code><span class="nolinebreak">__VA_ARGS__</span><!-- /@w --></code>), which +is still supported for backward compatibility. +</p> +<hr> +<div class="header"> +<p> +Next: <a href="Predefined-Macros.html#Predefined-Macros" accesskey="n" rel="next">Predefined Macros</a>, Previous: <a href="Concatenation.html#Concatenation" accesskey="p" rel="previous">Concatenation</a>, Up: <a href="Macros.html#Macros" accesskey="u" rel="up">Macros</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> |