cpp: Variadic Macros

1 
1 3.6 Variadic Macros
1 ===================
1 
1 A macro can be declared to accept a variable number of arguments much as
1 a function can.  The syntax for defining the macro is similar to that of
1 a function.  Here is an example:
1 
1      #define eprintf(...) fprintf (stderr, __VA_ARGS__)
1 
1    This kind of macro is called "variadic".  When the macro is invoked,
1 all the tokens in its argument list after the last named argument (this
1 macro has none), including any commas, become the "variable argument".
1 This sequence of tokens replaces the identifier '__VA_ARGS__' in the
1 macro body wherever it appears.  Thus, we have this expansion:
1 
1      eprintf ("%s:%d: ", input_file, lineno)
1           ==>  fprintf (stderr, "%s:%d: ", input_file, lineno)
1 
1    The variable argument is completely macro-expanded before it is
1 inserted into the macro expansion, just like an ordinary argument.  You
1 may use the '#' and '##' operators to stringize the variable argument or
1 to paste its leading or trailing token with another token.  (But see
1 below for an important special case for '##'.)
1 
1    If your macro is complicated, you may want a more descriptive name
1 for the variable argument than '__VA_ARGS__'.  CPP permits this, as an
1 extension.  You may write an argument name immediately before the '...';
1 that name is used for the variable argument.  The 'eprintf' macro above
1 could be written
1 
1      #define eprintf(args...) fprintf (stderr, args)
1 
1 using this extension.  You cannot use '__VA_ARGS__' and this extension
1 in the same macro.
1 
1    You can have named arguments as well as variable arguments in a
1 variadic macro.  We could define 'eprintf' like this, instead:
1 
1      #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__)
1 
1 This formulation looks more descriptive, but historically it was less
1 flexible: you had to supply at least one argument after the format
1 string.  In standard C, you could not omit the comma separating the
1 named argument from the variable arguments.  (Note that this restriction
1 has been lifted in C++2a, and never existed in GNU C; see below.)
1 
1    Furthermore, if you left the variable argument empty, you would have
1 gotten a syntax error, because there would have been an extra comma
1 after the format string.
1 
1      eprintf("success!\n", );
1           ==> fprintf(stderr, "success!\n", );
1 
1    This has been fixed in C++2a, and GNU CPP also has a pair of
1 extensions which deal with this problem.
1 
1    First, in GNU CPP, and in C++ beginning in C++2a, you are allowed to
1 leave the variable argument out entirely:
1 
1      eprintf ("success!\n")
1           ==> fprintf(stderr, "success!\n", );
1 
1 Second, C++2a introduces the '__VA_OPT__' function macro.  This macro
1 may only appear in the definition of a variadic macro.  If the variable
1 argument has any tokens, then a '__VA_OPT__' invocation expands to its
1 argument; but if the variable argument does not have any tokens, the
1 '__VA_OPT__' expands to nothing:
1 
1      #define eprintf(format, ...) \
1        fprintf (stderr, format __VA_OPT__(,) __VA_ARGS__)
1 
1    '__VA_OPT__' is also available in GNU C and GNU C++.
1 
1    Historically, GNU CPP has also had another extension to handle the
1 trailing comma: the '##' token paste operator has a special meaning when
1 placed between a comma and a variable argument.  Despite the
1 introduction of '__VA_OPT__', this extension remains supported in GNU
1 CPP, for backward compatibility.  If you write
1 
1      #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__)
1 
1 and the variable argument is left out when the 'eprintf' macro is used,
1 then the comma before the '##' will be deleted.  This does _not_ happen
1 if you pass an empty argument, nor does it happen if the token preceding
1 '##' is anything other than a comma.
1 
1      eprintf ("success!\n")
1           ==> fprintf(stderr, "success!\n");
1 
1 The above explanation is ambiguous about the case where the only macro
1 parameter is a variable arguments parameter, as it is meaningless to try
1 to distinguish whether no argument at all is an empty argument or a
1 missing argument.  CPP retains the comma when conforming to a specific C
1 standard.  Otherwise the comma is dropped as an extension to the
1 standard.
1 
1    The C standard mandates that the only place the identifier
1 '__VA_ARGS__' can appear is in the replacement list of a variadic macro.
1 It may not be used as a macro name, macro argument name, or within a
1 different type of macro.  It may also be forbidden in open text; the
1 standard is ambiguous.  We recommend you avoid using it except for its
1 defined purpose.
1 
1    Likewise, C++ forbids '__VA_OPT__' anywhere outside the replacement
1 list of a variadic macro.
1 
1    Variadic macros became a standard part of the C language with C99.
1 GNU CPP previously supported them with a named variable argument
1 ('args...', not '...' and '__VA_ARGS__'), which is still supported for
1 backward compatibility.
1