SEC12a.hss 4.4 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586
  1. [Main]
  2. Title=Macro Arguments
  3. [Top]
  4. Function-like macros can take <U>arguments</U>, just like true functions.
  5. To define a macro that uses arguments, you insert <U>parameters</U>
  6. between the pair of parentheses in the macro definition that make the
  7. macro function-like. The parameters must be valid C identifiers,
  8. separated by commas and optionally whitespace.
  9. <BR><BR>
  10. To invoke a macro that takes arguments, you write the name of the macro
  11. followed by a list of <U>actual arguments</U> in parentheses, separated
  12. by commas. The invocation of the macro need not be restricted to a
  13. single logical line - it can cross as many lines in the source file as
  14. you wish. The number of arguments you give must match the number of
  15. parameters in the macro definition. When the macro is expanded, each
  16. use of a parameter in its body is replaced by the tokens of the
  17. corresponding argument. (You need not use all of the parameters in the
  18. macro body.)
  19. <BR><BR>
  20. As an example, here is a macro that computes the minimum of two numeric
  21. values, as it is defined in many C programs, and some uses.
  22. <PRE>#define min(X, Y) ((X) &lt; (Y) ? (X) : (Y))
  23. x = min(a, b); expands to x = ((a) &lt; (b) ? (a) : (b));
  24. y = min(1, 2); expands to y = ((1) &lt; (2) ? (1) : (2));
  25. z = min(a + 28, *p); expands to z = ((a + 28) &lt; (*p) ? (a + 28) : (*p));
  26. </PRE>
  27. (In this small example you can already see several of the dangers of
  28. macro arguments. See <A HREF="$$LINK(SEC22)">Macro Pitfalls</A> for detailed explanations.)
  29. <BR><BR>
  30. Leading and trailing whitespace in each argument is dropped, and all
  31. whitespace between the tokens of an argument is reduced to a single
  32. space. Parentheses within each argument must balance; a comma within
  33. such parentheses does not end the argument. However, there is no
  34. requirement for square brackets or braces to balance, and they do not
  35. prevent a comma from separating arguments. Thus,
  36. <PRE>macro (array[x = y, x + 1])
  37. </PRE>
  38. passes two arguments to <CODE>macro</CODE>: <CODE>array[x&nbsp;=&nbsp;y</CODE> and <CODE>x&nbsp;+
  39. 1]</CODE>. If you want to supply <CODE>array[x&nbsp;=&nbsp;y,&nbsp;x&nbsp;+&nbsp;1]</CODE> as an argument,
  40. you can write it as <CODE>array[(x&nbsp;=&nbsp;y,&nbsp;x&nbsp;+&nbsp;1)]</CODE>, which is equivalent C
  41. code.
  42. <BR><BR>
  43. All arguments to a macro are completely macro-expanded before they are
  44. substituted into the macro body. After substitution, the complete text
  45. is scanned again for macros to expand, including the arguments. This rule
  46. may seem strange, but it is carefully designed so you need not worry
  47. about whether any function call is actually a macro invocation. You can
  48. run into trouble if you try to be too clever, though. See <A HREF="$$LINK(SEC28)">Argument
  49. Prescan</A> for detailed discussion.
  50. <BR><BR>
  51. For example, <CODE>min&nbsp;(min&nbsp;(a,&nbsp;b),&nbsp;c)</CODE> is first expanded to
  52. <PRE> min (((a) &lt; (b) ? (a) : (b)), (c))
  53. </PRE>
  54. and then to
  55. <PRE>((((a) &lt; (b) ? (a) : (b))) &lt; (c)
  56. ? (((a) &lt; (b) ? (a) : (b)))
  57. : (c))
  58. </PRE>
  59. (Line breaks shown here for clarity would not actually be generated.)
  60. <BR><BR>
  61. You can leave macro arguments empty; this is not an error to the
  62. preprocessor (but many macros will then expand to invalid code).
  63. You cannot leave out arguments entirely; if a macro takes two arguments,
  64. there must be exactly one comma at the top level of its argument list.
  65. Here are some silly examples using <CODE>min</CODE>:
  66. <PRE>min(, b) expands to (( ) &lt; (b) ? ( ) : (b))
  67. min(a, ) expands to ((a ) &lt; ( ) ? (a ) : ( ))
  68. min(,) expands to (( ) &lt; ( ) ? ( ) : ( ))
  69. min((,),) expands to (((,)) &lt; ( ) ? ((,)) : ( ))
  70. min() Error: macro &quot;min&quot; requires 2 arguments, but only 1 given
  71. min(,,) Error: macro &quot;min&quot; passed 3 arguments, but takes just 2
  72. </PRE>
  73. Whitespace is not a preprocessing token, so if a macro <CODE>foo</CODE> takes
  74. one argument, <CODE>foo&nbsp;()</CODE> and <CODE>foo&nbsp;(&nbsp;)</CODE> both supply it an
  75. empty argument. Previous GNU preprocessor implementations and
  76. documentation were incorrect on this point, insisting that a
  77. function-like macro that takes a single argument be passed a space if an
  78. empty argument was required.
  79. <BR><BR>
  80. Macro parameters appearing inside string literals are not replaced by
  81. their corresponding actual arguments.
  82. <PRE>#define foo(x) x, &quot;x&quot;
  83. foo(bar) expands to bar, &quot;x&quot;
  84. </PRE>