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