home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 6 / FreshFish_September1994.bin / gnu / info / cpp.info-2 (.txt) < prev    next >
GNU Info File  |  1994-09-02  |  40KB  |  728 lines
  1. This is Info file cpp.info, produced by Makeinfo-1.54 from the input
  2. file cpp.texi.
  3.    This file documents the GNU C Preprocessor.
  4.    Copyright 1987, 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  5.    Permission is granted to make and distribute verbatim copies of this
  6. manual provided the copyright notice and this permission notice are
  7. preserved on all copies.
  8.    Permission is granted to copy and distribute modified versions of
  9. this manual under the conditions for verbatim copying, provided also
  10. that the entire resulting derived work is distributed under the terms
  11. of a permission notice identical to this one.
  12.    Permission is granted to copy and distribute translations of this
  13. manual into another language, under the above conditions for modified
  14. versions.
  15. File: cpp.info,  Node: Macro Parentheses,  Next: Swallow Semicolon,  Prev: Misnesting,  Up: Macro Pitfalls
  16. Unintended Grouping of Arithmetic
  17. .................................
  18.    You may have noticed that in most of the macro definition examples
  19. shown above, each occurrence of a macro argument name had parentheses
  20. around it.  In addition, another pair of parentheses usually surround
  21. the entire macro definition.  Here is why it is best to write macros
  22. that way.
  23.    Suppose you define a macro as follows,
  24.      #define ceil_div(x, y) (x + y - 1) / y
  25. whose purpose is to divide, rounding up.  (One use for this operation is
  26. to compute how many `int' objects are needed to hold a certain number
  27. of `char' objects.)  Then suppose it is used as follows:
  28.      a = ceil_div (b & c, sizeof (int));
  29. This expands into
  30.      a = (b & c + sizeof (int) - 1) / sizeof (int);
  31. which does not do what is intended.  The operator-precedence rules of C
  32. make it equivalent to this:
  33.      a = (b & (c + sizeof (int) - 1)) / sizeof (int);
  34. But what we want is this:
  35.      a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
  36. Defining the macro as
  37.      #define ceil_div(x, y) ((x) + (y) - 1) / (y)
  38. provides the desired result.
  39.    However, unintended grouping can result in another way.  Consider
  40. `sizeof ceil_div(1, 2)'.  That has the appearance of a C expression
  41. that would compute the size of the type of `ceil_div (1, 2)', but in
  42. fact it means something very different.  Here is what it expands to:
  43.      sizeof ((1) + (2) - 1) / (2)
  44. This would take the size of an integer and divide it by two.  The
  45. precedence rules have put the division outside the `sizeof' when it was
  46. intended to be inside.
  47.    Parentheses around the entire macro definition can prevent such
  48. problems.  Here, then, is the recommended way to define `ceil_div':
  49.      #define ceil_div(x, y) (((x) + (y) - 1) / (y))
  50. File: cpp.info,  Node: Swallow Semicolon,  Next: Side Effects,  Prev: Macro Parentheses,  Up: Macro Pitfalls
  51. Swallowing the Semicolon
  52. ........................
  53.    Often it is desirable to define a macro that expands into a compound
  54. statement.  Consider, for example, the following macro, that advances a
  55. pointer (the argument `p' says where to find it) across whitespace
  56. characters:
  57.      #define SKIP_SPACES (p, limit)  \
  58.      { register char *lim = (limit); \
  59.        while (p != lim) {            \
  60.          if (*p++ != ' ') {          \
  61.            p--; break; }}}
  62. Here Backslash-Newline is used to split the macro definition, which must
  63. be a single line, so that it resembles the way such C code would be
  64. laid out if not part of a macro definition.
  65.    A call to this macro might be `SKIP_SPACES (p, lim)'.  Strictly
  66. speaking, the call expands to a compound statement, which is a complete
  67. statement with no need for a semicolon to end it.  But it looks like a
  68. function call.  So it minimizes confusion if you can use it like a
  69. function call, writing a semicolon afterward, as in `SKIP_SPACES (p,
  70. lim);'
  71.    But this can cause trouble before `else' statements, because the
  72. semicolon is actually a null statement.  Suppose you write
  73.      if (*p != 0)
  74.        SKIP_SPACES (p, lim);
  75.      else ...
  76. The presence of two statements--the compound statement and a null
  77. statement--in between the `if' condition and the `else' makes invalid C
  78. code.
  79.    The definition of the macro `SKIP_SPACES' can be altered to solve
  80. this problem, using a `do ... while' statement.  Here is how:
  81.      #define SKIP_SPACES (p, limit)     \
  82.      do { register char *lim = (limit); \
  83.           while (p != lim) {            \
  84.             if (*p++ != ' ') {          \
  85.               p--; break; }}}           \
  86.      while (0)
  87.    Now `SKIP_SPACES (p, lim);' expands into
  88.      do {...} while (0);
  89. which is one statement.
  90. File: cpp.info,  Node: Side Effects,  Next: Self-Reference,  Prev: Swallow Semicolon,  Up: Macro Pitfalls
  91. Duplication of Side Effects
  92. ...........................
  93.    Many C programs define a macro `min', for "minimum", like this:
  94.      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
  95.    When you use this macro with an argument containing a side effect,
  96. as shown here,
  97.      next = min (x + y, foo (z));
  98. it expands as follows:
  99.      next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
  100. where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
  101.    The function `foo' is used only once in the statement as it appears
  102. in the program, but the expression `foo (z)' has been substituted twice
  103. into the macro expansion.  As a result, `foo' might be called two times
  104. when the statement is executed.  If it has side effects or if it takes
  105. a long time to compute, the results might not be what you intended.  We
  106. say that `min' is an "unsafe" macro.
  107.    The best solution to this problem is to define `min' in a way that
  108. computes the value of `foo (z)' only once.  The C language offers no
  109. standard way to do this, but it can be done with GNU C extensions as
  110. follows:
  111.      #define min(X, Y)                     \
  112.      ({ typeof (X) __x = (X), __y = (Y);   \
  113.         (__x < __y) ? __x : __y; })
  114.    If you do not wish to use GNU C extensions, the only solution is to
  115. be careful when *using* the macro `min'.  For example, you can
  116. calculate the value of `foo (z)', save it in a variable, and use that
  117. variable in `min':
  118.      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
  119.      ...
  120.      {
  121.        int tem = foo (z);
  122.        next = min (x + y, tem);
  123.      }
  124. (where we assume that `foo' returns type `int').
  125. File: cpp.info,  Node: Self-Reference,  Next: Argument Prescan,  Prev: Side Effects,  Up: Macro Pitfalls
  126. Self-Referential Macros
  127. .......................
  128.    A "self-referential" macro is one whose name appears in its
  129. definition.  A special feature of ANSI Standard C is that the
  130. self-reference is not considered a macro call.  It is passed into the
  131. preprocessor output unchanged.
  132.    Let's consider an example:
  133.      #define foo (4 + foo)
  134. where `foo' is also a variable in your program.
  135.    Following the ordinary rules, each reference to `foo' will expand
  136. into `(4 + foo)'; then this will be rescanned and will expand into `(4
  137. + (4 + foo))'; and so on until it causes a fatal error (memory full) in
  138. the preprocessor.
  139.    However, the special rule about self-reference cuts this process
  140. short after one step, at `(4 + foo)'.  Therefore, this macro definition
  141. has the possibly useful effect of causing the program to add 4 to the
  142. value of `foo' wherever `foo' is referred to.
  143.    In most cases, it is a bad idea to take advantage of this feature.  A
  144. person reading the program who sees that `foo' is a variable will not
  145. expect that it is a macro as well.  The reader will come across the
  146. identifier `foo' in the program and think its value should be that of
  147. the variable `foo', whereas in fact the value is four greater.
  148.    The special rule for self-reference applies also to "indirect"
  149. self-reference.  This is the case where a macro X expands to use a
  150. macro `y', and the expansion of `y' refers to the macro `x'.  The
  151. resulting reference to `x' comes indirectly from the expansion of `x',
  152. so it is a self-reference and is not further expanded.  Thus, after
  153.      #define x (4 + y)
  154.      #define y (2 * x)
  155. `x' would expand into `(4 + (2 * x))'.  Clear?
  156.    But suppose `y' is used elsewhere, not from the definition of `x'.
  157. Then the use of `x' in the expansion of `y' is not a self-reference
  158. because `x' is not "in progress".  So it does expand.  However, the
  159. expansion of `x' contains a reference to `y', and