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