]>
Commit | Line | Data |
---|---|---|
d405059b | 1 | # DP: cpp.texi: add a node documenting macro varargs. |
2 | ||
3 | Sat Aug 7 14:56:50 1999 Matthias Klose <doko@cs.tu-berlin.de> | |
4 | ||
5 | * cpp.texi: cpp.texi: add a node documenting macro varargs (copied | |
6 | from extend.texi. | |
7 | ||
8 | --- gcc/cpp.texi~ Wed May 19 13:22:57 1999 | |
9 | +++ gcc/cpp.texi Sat Aug 7 14:53:42 1999 | |
10 | @@ -542,6 +542,7 @@ | |
11 | * Simple Macros:: Macros that always expand the same way. | |
12 | * Argument Macros:: Macros that accept arguments that are substituted | |
13 | into the macro expansion. | |
14 | +* Macro Varargs:: Macros with variable number of arguments. | |
15 | * Predefined:: Predefined macros that are always available. | |
16 | * Stringification:: Macro arguments converted into string constants. | |
17 | * Concatenation:: Building tokens from parts taken from macro arguments. | |
18 | @@ -645,7 +646,7 @@ | |
19 | that the result of its expansion is checked for more macro names. | |
20 | @xref{Cascaded Macros}. | |
21 | ||
22 | -@node Argument Macros, Predefined, Simple Macros, Macros | |
23 | +@node Argument Macros, Macro Varargs, Simple Macros, Macros | |
24 | @subsection Macros with Arguments | |
25 | @cindex macros with argument | |
26 | @cindex arguments in macro definitions | |
27 | @@ -799,7 +800,68 @@ | |
28 | the left parenthesis; it's the @emph{definition} where it matters whether | |
29 | there is a space. | |
30 | ||
31 | -@node Predefined, Stringification, Argument Macros, Macros | |
32 | +@node Macro Varargs, Predefined, Argument Macros, Macros | |
33 | +@subsection Macros with Variable Numbers of Arguments | |
34 | +@cindex variable number of arguments | |
35 | +@cindex macro with variable arguments | |
36 | +@cindex rest argument (in macro) | |
37 | + | |
38 | +In GNU C, a macro can accept a variable number of arguments, much as a | |
39 | +function can. The syntax for defining the macro looks much like that | |
40 | +used for a function. Here is an example: | |
41 | + | |
42 | +@example | |
43 | +#define eprintf(format, args...) \ | |
44 | + fprintf (stderr, format , ## args) | |
45 | +@end example | |
46 | + | |
47 | +Here @code{args} is a @dfn{rest argument}: it takes in zero or more | |
48 | +arguments, as many as the call contains. All of them plus the commas | |
49 | +between them form the value of @code{args}, which is substituted into | |
50 | +the macro body where @code{args} is used. Thus, we have this expansion: | |
51 | + | |
52 | +@example | |
53 | +eprintf ("%s:%d: ", input_file_name, line_number) | |
54 | +@expansion{} | |
55 | +fprintf (stderr, "%s:%d: " , input_file_name, line_number) | |
56 | +@end example | |
57 | + | |
58 | +@noindent | |
59 | +Note that the comma after the string constant comes from the definition | |
60 | +of @code{eprintf}, whereas the last comma comes from the value of | |
61 | +@code{args}. | |
62 | + | |
63 | +The reason for using @samp{##} is to handle the case when @code{args} | |
64 | +matches no arguments at all. In this case, @code{args} has an empty | |
65 | +value. In this case, the second comma in the definition becomes an | |
66 | +embarrassment: if it got through to the expansion of the macro, we would | |
67 | +get something like this: | |
68 | + | |
69 | +@example | |
70 | +fprintf (stderr, "success!\n" , ) | |
71 | +@end example | |
72 | + | |
73 | +@noindent | |
74 | +which is invalid C syntax. @samp{##} gets rid of the comma, so we get | |
75 | +the following instead: | |
76 | + | |
77 | +@example | |
78 | +fprintf (stderr, "success!\n") | |
79 | +@end example | |
80 | + | |
81 | +This is a special feature of the GNU C preprocessor: @samp{##} before a | |
82 | +rest argument that is empty discards the preceding sequence of | |
83 | +non-whitespace characters from the macro definition. (If another macro | |
84 | +argument precedes, none of it is discarded.) | |
85 | + | |
86 | +It might be better to discard the last preprocessor token instead of the | |
87 | +last preceding sequence of non-whitespace characters; in fact, we may | |
88 | +someday change this feature to do so. We advise you to write the macro | |
89 | +definition so that the preceding sequence of non-whitespace characters | |
90 | +is just a single token, so that the meaning will not change if we change | |
91 | +the definition of this feature. | |
92 | + | |
93 | +@node Predefined, Stringification, Macro Varargs, Macros | |
94 | @subsection Predefined Macros | |
95 | ||
96 | @cindex predefined macros |