From 21c8d03dde9620f3bb8140c4c98bd1cf54085017 Mon Sep 17 00:00:00 2001
From: Matthias Klose <doko@cs.tu-berlin.de>
Date: Tue, 24 Aug 1999 05:37:39 +0000
Subject: [PATCH] cpp.texi: Add a node documenting macro varargs (copied from extend.texi).
* cpp.texi: Add a node documenting macro varargs (copied
from extend.texi).
From-SVN: r28814
---
gcc/ChangeLog | 5 +++++
gcc/cpp.texi | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
2 files changed, 69 insertions(+), 2 deletions(-)
diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 3b77de2..cd9581e 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+Mon Aug 23 23:35:52 1999 Matthias Klose <doko@cs.tu-berlin.de>
+
+ * cpp.texi: Add a node documenting macro varargs (copied
+ from extend.texi).
+
1999-08-23 22:23 -0700 Zack Weinberg <zack@bitmover.com>
* cppspec.c: Put a null pointer at the end of the new argv.
diff --git a/gcc/cpp.texi b/gcc/cpp.texi
index 4afcd97..5860f1c 100644
--- a/gcc/cpp.texi
+++ b/gcc/cpp.texi
@@ -545,6 +545,7 @@ in the C preprocessor.
* Simple Macros:: Macros that always expand the same way.
* Argument Macros:: Macros that accept arguments that are substituted
into the macro expansion.
+* Macro Varargs:: Macros with variable number of arguments.
* Predefined:: Predefined macros that are always available.
* Stringification:: Macro arguments converted into string constants.
* Concatenation:: Building tokens from parts taken from macro arguments.
@@ -648,7 +649,7 @@ it too is the name of a macro. It's only when you @emph{use} @samp{TABLESIZE}
that the result of its expansion is checked for more macro names.
@xref{Cascaded Macros}.
-@node Argument Macros, Predefined, Simple Macros, Macros
+@node Argument Macros, Macro Varargs, Simple Macros, Macros
@subsection Macros with Arguments
@cindex macros with argument
@cindex arguments in macro definitions
@@ -802,7 +803,68 @@ Note that the @emph{uses} of a macro with arguments can have spaces before
the left parenthesis; it's the @emph{definition} where it matters whether
there is a space.
-@node Predefined, Stringification, Argument Macros, Macros
+@node Macro Varargs, Predefined, Argument Macros, Macros
+@subsection Macros with Variable Numbers of Arguments
+@cindex variable number of arguments
+@cindex macro with variable arguments
+@cindex rest argument (in macro)
+
+In GNU C, a macro can accept a variable number of arguments, much as a
+function can. The syntax for defining the macro looks much like that
+used for a function. Here is an example:
+
+@example
+#define eprintf(format, args...) \
+ fprintf (stderr, format , ## args)
+@end example
+
+Here @code{args} is a @dfn{rest argument}: it takes in zero or more
+arguments, as many as the call contains. All of them plus the commas
+between them form the value of @code{args}, which is substituted into
+the macro body where @code{args} is used. Thus, we have this expansion:
+
+@example
+eprintf ("%s:%d: ", input_file_name, line_number)
+@expansion{}
+fprintf (stderr, "%s:%d: " , input_file_name, line_number)
+@end example
+
+@noindent
+Note that the comma after the string constant comes from the definition
+of @code{eprintf}, whereas the last comma comes from the value of
+@code{args}.
+
+The reason for using @samp{##} is to handle the case when @code{args}
+matches no arguments at all. In this case, @code{args} has an empty
+value. In this case, the second comma in the definition becomes an
+embarrassment: if it got through to the expansion of the macro, we would
+get something like this:
+
+@example
+fprintf (stderr, "success!\n" , )
+@end example
+
+@noindent
+which is invalid C syntax. @samp{##} gets rid of the comma, so we get
+the following instead:
+
+@example
+fprintf (stderr, "success!\n")
+@end example
+
+This is a special feature of the GNU C preprocessor: @samp{##} before a
+rest argument that is empty discards the preceding sequence of
+non-whitespace characters from the macro definition. (If another macro
+argument precedes, none of it is discarded.)
+
+It might be better to discard the last preprocessor token instead of the
+last preceding sequence of non-whitespace characters; in fact, we may
+someday change this feature to do so. We advise you to write the macro
+definition so that the preceding sequence of non-whitespace characters
+is just a single token, so that the meaning will not change if we change
+the definition of this feature.
+
+@node Predefined, Stringification, Macro Varargs, Macros
@subsection Predefined Macros
@cindex predefined macros
--
libgit2 0.26.0