Editing Variadic macro in the C preprocessor

{{Short description|Macro taking a varying number of arguments}}
A '''variadic macro''' is a feature of some computer [[programming language]]s, especially the [[C preprocessor]], whereby a [[macro (computer science)|macro]] may be declared to accept a varying number of [[parameter (computer programming)|arguments]]. 

Variable-argument macros were introduced in 1999 in the ''ISO/IEC 9899:1999'' ([[C99]]) revision of the [[C (programming language)|C]] language standard, and in 2011 in ''ISO/IEC 14882:2011'' ([[C++11]]) revision of the [[C++]] language standard.<ref>Working draft changes for C99 preprocessor synchronization – http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1653.htm</ref> Support for variadic macros with no arguments was added in [[C++20]] and will be added in [[C23 (C standard revision)|C23]].<ref>{{cite web|url=https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0306r3.html|title=Comma omission and comma deletion|date=June 18, 2017|access-date=December 24, 2022}}</ref><ref name=N3033/><!-- The first source is the C++ version and the second the C version. They are not duplicates. -->

== Declaration syntax ==
The declaration syntax is similar to that of [[variadic function]]s: a sequence of three [[full stop]]s "{{var|...}}" is used to indicate that one or more arguments must be passed. During macro expansion each occurrence of the special identifier {{var|__VA_ARGS__}} in the macro replacement list is replaced by the passed arguments.

Additionally, regular macro arguments may be listed before the <code>...</code>,<ref name="gcc" /> but regular arguments may not be listed after the <code>...</code>.

No means is provided to access individual arguments in the variable argument list, nor to find out how many were passed. However, macros can be written to count the number of arguments that have been passed.<ref>{{cite newsgroup
 |author= Laurent Deniau
 |title= __VA_NARG__
 |date= 2006-01-16
 |newsgroup= comp.std.c
 |message-id= dqgm2f$ije$1@sunnews.cern.ch
 |url= http://groups.google.com/group/comp.std.c/browse_thread/thread/77ee8c8f92e4a3fb/346fc464319b1ee5
}}</ref>

Both the [[C99]] and [[C++11]] standards require at least one argument, but since [[C++20]] this limitation has been lifted through the {{var|__VA_OPT__}} functional macro. The {{var|__VA_OPT__}} macro is replaced by its argument when arguments are present, and omitted otherwise. Common compilers also permit passing zero arguments before this addition, however.<ref name="gcc">[https://gcc.gnu.org/onlinedocs/gcc/Variadic-Macros.html Variadic Macros – Using the GNU Compiler Collection (GCC)]</ref><ref name="msvc">[https://msdn.microsoft.com/en-us/library/ms177415(v=vs.140).aspx Variadic Macros (C++)]</ref>

The C preprocessor rules prevent macro names in the argument of {{var|__VA_OPT__}} from expanding recursively.  It is possible to work around this limitation up to an arbitrary fixed number of recursive expansions, however.<ref name="recursive-vaopt">[https://www.scs.stanford.edu/~dm/blog/va-opt.html Recursive macros with C++20 __VA_OPT__]</ref>

== Support ==
Several [[compiler]]s support variable-argument macros when compiling C and C++ code: the [[GNU Compiler Collection]] 3.0,<ref name="gcc" /> [[Clang]] (all versions),<ref>Clang source code change that mentions __VA_ARGS__ support (2006-07-29), note that Clang was open-sourced in 2007. http://llvm.org/viewvc/llvm-project?view=revision&revision=38770</ref> [[Visual Studio 2005]],<ref name="msvc" /> [[C++Builder]] 2006, and [[Oracle Solaris Studio]] (formerly Sun Studio) Forte Developer 6 update 2 (C++ version 5.3).<ref>Sun Studio feature comparison – http://developers.sun.com/sunstudio/support/CCcompare.html</ref>  GCC also supports such macros when compiling [[Objective-C]].

Support for the {{var|__VA_OPT__}} macro to support zero arguments has been added in [[GNU Compiler Collection]] 8,<ref>{{cite web|url=https://gcc.gnu.org/projects/cxx-status.html#cxx2a|title=C++2a Support in GCC|access-date=June 14, 2018}}</ref> [[Clang]] 6,<ref>{{cite web|url=https://clang.llvm.org/cxx_status.html|title=C++ Support in Clang|access-date=June 14, 2018}}</ref> and [[Visual Studio 2019]].<ref>{{cite web|url=https://docs.microsoft.com/en-us/cpp/preprocessor/preprocessor-experimental-overview|title=MSVC new preprocessor overview|date=September 10, 2020|access-date=December 8, 2020}}</ref>

== Example ==
If a <code>[[printf]]</code>-like [[subroutine|function]] {{code|dbgprintf()}} were desired, which would take the file and line number from which it was called as arguments, the following solution applies.
<!-- Don't change the example back to dprintf; it is a POSIX function: http://pubs.opengroup.org/onlinepubs/9699919799/functions/dprintf.html -->
{{olist
|Our implemented function
<syntaxhighlight lang="c">
void realdbgprintf (const char *SourceFilename,
                    int SourceLineno,
                    const char *CFormatString,
                    ...);
</syntaxhighlight>
| <p>Due to limitations of the variadic macro support in C++11 the following
straightforward solution can fail and should thus be avoided:</p>
<syntaxhighlight lang="cpp">
   #define dbgprintf(cformat, ...) \
     realdbgprintf (__FILE__, __LINE__, cformat, __VA_ARGS__)
</syntaxhighlight>
The reason is that
<syntaxhighlight lang="cpp">
   dbgprintf("Hallo")
</syntaxhighlight>
gets expanded to
<syntaxhighlight lang="cpp">
   realdbgprintf (__FILE__, __LINE__, "Hallo", )
</syntaxhighlight>
where the comma before the closing brace will result in a syntax error.
| GNU C++ supports a non-portable extension which solves this.
<syntaxhighlight lang="c">
   #define dbgprintf(cformat, ...) \
     realdbgprintf (__FILE__, __LINE__, cformat, ##__VA_ARGS__)
</syntaxhighlight>
| C++20 eventually supports the following syntax.
<syntaxhighlight lang="cpp">
   #define dbgprintf(cformat, ...) \
     realdbgprintf (__FILE__, __LINE__, cformat __VA_OPT__(,) __VA_ARGS__)
</syntaxhighlight>
| By using the 'cformat' string as part of the variadic arguments we can
circumvent the abovementioned incompatibilities.  This is tricky but
portable.
<syntaxhighlight lang="c">
#define dbgprintf(...) realdbgprintf (__FILE__, __LINE__, __VA_ARGS__)
</syntaxhighlight>
}}
{{code|dbgprintf()}} could then be called as
<syntaxhighlight lang="c">
dbgprintf ("Hello, world");
</syntaxhighlight>
which expands to
<syntaxhighlight lang="c">
realdbgprintf (__FILE__, __LINE__, "Hello, world");
</syntaxhighlight>

Another example is
<syntaxhighlight lang="c">
dbgprintf("%d + %d = %d", 2, 2, 5);
</syntaxhighlight>
which expands to
<syntaxhighlight lang="c">
realdbgprintf(__FILE__, __LINE__, "%d + %d = %d", 2, 2, 5);
</syntaxhighlight>

Without variadic macros, writing wrappers to <code>[[printf]]</code> is not directly possible.  The standard workaround is to use the [[Stdarg.h|stdargs]] functionality of C/C++, and have the function call <code>[[vprintf]]</code> instead.

== Trailing comma ==
There is a portability issue with generating a trailing comma with empty args for variadic macros in [[C99]]. Some compilers (e.g., Visual Studio when not using the new standard-conformant preprocessor<ref name="msvc" />) will silently eliminate the trailing comma. Other compilers (e.g.: GCC<ref name="gcc" />) support putting {{code|##}} in front of <code>{{var|__VA_ARGS__}}</code>.

<syntaxhighlight lang="c">
# define MYLOG(FormatLiteral, ...)  fprintf (stderr, "%s(%u): " FormatLiteral "\n", __FILE__, __LINE__, __VA_ARGS__)
</syntaxhighlight>
The following application works
<syntaxhighlight lang="c">
MYLOG("Too many balloons %u", 42);
</syntaxhighlight>
which expands to
<syntaxhighlight lang="c">
fprintf (stderr, "%s(%u): " "Too many balloons %u" "\n", __FILE__, __LINE__, 42);
</syntaxhighlight>
which is equivalent to
<syntaxhighlight lang="c">
fprintf (stderr, "%s(%u): Too many balloons %u\n", __FILE__, __LINE__, 42);
</syntaxhighlight>
But look at this application:
<syntaxhighlight lang="c">
MYLOG("Attention!");
</syntaxhighlight>
which expands to
<syntaxhighlight lang="c">
fprintf (stderr, "%s(%u): " "Attention!" "\n", __FILE__, __LINE__, );
</syntaxhighlight>
which generates a syntax error with GCC.

GCC supports the following (non-portable) extension:
<syntaxhighlight lang="c">
# define MYLOG(FormatLiteral, ...)  fprintf (stderr, "%s(%u): " FormatLiteral "\n", __FILE__, __LINE__, ##__VA_ARGS__)
</syntaxhighlight>
which removes the trailing comma when <code>{{var|__VA_ARGS__}}</code> is empty.

[[C23 (C standard revision)|C23]] solves this problem by introducing <code>{{var|__VA_OPT__}}</code> like C++.<ref name=N3033>{{cite web|url=https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3033.htm|title=WG14 - N3033 : Comma omission and comma deletion|date=2022-07-20}}</ref>

== Alternatives ==
Before the existence of variable-arguments in C99, it was quite common to use doubly nested parentheses to exploit the variable number of arguments that could be supplied to the {{code|printf()}} function:

<syntaxhighlight lang="c">
#define dbgprintf(x) realdbgprintf x
</syntaxhighlight>
{{code|dbgprintf()}} could then be called as:
<syntaxhighlight lang="c">
dbgprintf (("Hello, world %d", 27));
</syntaxhighlight>
which expands to:
<syntaxhighlight lang="c">
realdbgprintf ("Hello, world %d", 27);
</syntaxhighlight>

== References ==
{{Reflist}}

== See also ==
* [[Variadic function]]
* [[Variadic template]]

[[Category:C (programming language)]]
[[Category:C++]]

[[ja:可変長引数]]