cpp: Macro Arguments

1 
1 3.3 Macro Arguments
1 ===================
1 
1 Function-like macros can take "arguments", just like true functions.  To
1 define a macro that uses arguments, you insert "parameters" between the
1 pair of parentheses in the macro definition that make the macro
1 function-like.  The parameters must be valid C identifiers, separated by
1 commas and optionally whitespace.
1 
1    To invoke a macro that takes arguments, you write the name of the
1 macro followed by a list of "actual arguments" in parentheses, separated
1 by commas.  The invocation of the macro need not be restricted to a
1 single logical line--it can cross as many lines in the source file as
1 you wish.  The number of arguments you give must match the number of
1 parameters in the macro definition.  When the macro is expanded, each
1 use of a parameter in its body is replaced by the tokens of the
1 corresponding argument.  (You need not use all of the parameters in the
1 macro body.)
1 
1    As an example, here is a macro that computes the minimum of two
1 numeric values, as it is defined in many C programs, and some uses.
1 
1      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
1        x = min(a, b);          ==>  x = ((a) < (b) ? (a) : (b));
1        y = min(1, 2);          ==>  y = ((1) < (2) ? (1) : (2));
1        z = min(a + 28, *p);    ==>  z = ((a + 28) < (*p) ? (a + 28) : (*p));
1 
1 (In this small example you can already see several of the dangers of
1 macro arguments.  ⇒Macro Pitfalls, for detailed explanations.)
1 
1    Leading and trailing whitespace in each argument is dropped, and all
1 whitespace between the tokens of an argument is reduced to a single
1 space.  Parentheses within each argument must balance; a comma within
1 such parentheses does not end the argument.  However, there is no
1 requirement for square brackets or braces to balance, and they do not
1 prevent a comma from separating arguments.  Thus,
1 
1      macro (array[x = y, x + 1])
1 
1 passes two arguments to 'macro': 'array[x = y' and 'x + 1]'.  If you
1 want to supply 'array[x = y, x + 1]' as an argument, you can write it as
1 'array[(x = y, x + 1)]', which is equivalent C code.
1 
1    All arguments to a macro are completely macro-expanded before they
1 are substituted into the macro body.  After substitution, the complete
1 text is scanned again for macros to expand, including the arguments.
1 This rule may seem strange, but it is carefully designed so you need not
1 worry about whether any function call is actually a macro invocation.
11 You can run into trouble if you try to be too clever, though.  ⇒
 Argument Prescan, for detailed discussion.
1 
1    For example, 'min (min (a, b), c)' is first expanded to
1 
1        min (((a) < (b) ? (a) : (b)), (c))
1 
1 and then to
1 
1      ((((a) < (b) ? (a) : (b))) < (c)
1       ? (((a) < (b) ? (a) : (b)))
1       : (c))
1 
1 (Line breaks shown here for clarity would not actually be generated.)
1 
1    You can leave macro arguments empty; this is not an error to the
1 preprocessor (but many macros will then expand to invalid code).  You
1 cannot leave out arguments entirely; if a macro takes two arguments,
1 there must be exactly one comma at the top level of its argument list.
1 Here are some silly examples using 'min':
1 
1      min(, b)        ==> ((   ) < (b) ? (   ) : (b))
1      min(a, )        ==> ((a  ) < ( ) ? (a  ) : ( ))
1      min(,)          ==> ((   ) < ( ) ? (   ) : ( ))
1      min((,),)       ==> (((,)) < ( ) ? ((,)) : ( ))
1 
1      min()      error-> macro "min" requires 2 arguments, but only 1 given
1      min(,,)    error-> macro "min" passed 3 arguments, but takes just 2
1 
1    Whitespace is not a preprocessing token, so if a macro 'foo' takes
1 one argument, 'foo ()' and 'foo ( )' both supply it an empty argument.
1 Previous GNU preprocessor implementations and documentation were
1 incorrect on this point, insisting that a function-like macro that takes
1 a single argument be passed a space if an empty argument was required.
1 
1    Macro parameters appearing inside string literals are not replaced by
1 their corresponding actual arguments.
1 
1      #define foo(x) x, "x"
1      foo(bar)        ==> bar, "x"
1