home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / gnu / info / cpp.info-2 (.txt) < prev    next >
GNU Info File  |  1994-07-11  |  50KB  |  925 lines
  1. This is Info file cpp.info, produced by Makeinfo-1.55 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: Swallow Semicolon,  Next: Side Effects,  Prev: Macro Parentheses,  Up: Macro Pitfalls
  16. Swallowing the Semicolon
  17. ........................
  18.    Often it is desirable to define a macro that expands into a compound
  19. statement.  Consider, for example, the following macro, that advances a
  20. pointer (the argument `p' says where to find it) across whitespace
  21. characters:
  22.      #define SKIP_SPACES (p, limit)  \
  23.      { register char *lim = (limit); \
  24.        while (p != lim) {            \
  25.          if (*p++ != ' ') {          \
  26.            p--; break; }}}
  27. Here Backslash-Newline is used to split the macro definition, which must
  28. be a single line, so that it resembles the way such C code would be
  29. laid out if not part of a macro definition.
  30.    A call to this macro might be `SKIP_SPACES (p, lim)'.  Strictly
  31. speaking, the call expands to a compound statement, which is a complete
  32. statement with no need for a semicolon to end it.  But it looks like a
  33. function call.  So it minimizes confusion if you can use it like a
  34. function call, writing a semicolon afterward, as in `SKIP_SPACES (p,
  35. lim);'
  36.    But this can cause trouble before `else' statements, because the
  37. semicolon is actually a null statement.  Suppose you write
  38.      if (*p != 0)
  39.        SKIP_SPACES (p, lim);
  40.      else ...
  41. The presence of two statements--the compound statement and a null
  42. statement--in between the `if' condition and the `else' makes invalid C
  43. code.
  44.    The definition of the macro `SKIP_SPACES' can be altered to solve
  45. this problem, using a `do ... while' statement.  Here is how:
  46.      #define SKIP_SPACES (p, limit)     \
  47.      do { register char *lim = (limit); \
  48.           while (p != lim) {            \
  49.             if (*p++ != ' ') {          \
  50.               p--; break; }}}           \
  51.      while (0)
  52.    Now `SKIP_SPACES (p, lim);' expands into
  53.      do {...} while (0);
  54. which is one statement.
  55. File: cpp.info,  Node: Side Effects,  Next: Self-Reference,  Prev: Swallow Semicolon,  Up: Macro Pitfalls
  56. Duplication of Side Effects
  57. ...........................
  58.    Many C programs define a macro `min', for "minimum", like this:
  59.      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
  60.    When you use this macro with an argument containing a side effect,
  61. as shown here,
  62.      next = min (x + y, foo (z));
  63. it expands as follows:
  64.      next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
  65. where `x + y' has been substituted for `X' and `foo (z)' for `Y'.
  66.    The function `foo' is used only once in the statement as it appears
  67. in the program, but the expression `foo (z)' has been substituted twice
  68. into the macro expansion.  As a result, `foo' might be called two times
  69. when the statement is executed.  If it has side effects or if it takes
  70. a long time to compute, the results might not be what you intended.  We
  71. say that `min' is an "unsafe" macro.
  72.    The best solution to this problem is to define `min' in a way that
  73. computes the value of `foo (z)' only once.  The C language offers no
  74. standard way to do this, but it can be done with GNU C extensions as
  75. follows:
  76.      #define min(X, Y)                     \
  77.      ({ typeof (X) __x = (X), __y = (Y);   \
  78.         (__x < __y) ? __x : __y; })
  79.    If you do not wish to use GNU C extensions, the only solution is to
  80. be careful when *using* the macro `min'.  For example, you can
  81. calculate the value of `foo (z)', save it in a variable, and use that
  82. variable in `min':
  83.      #define min(X, Y)  ((X) < (Y) ? (X) : (Y))
  84.      ...
  85.      {
  86.        int tem = foo (z);
  87.        next = min (x + y, tem);
  88.      }
  89. (where we assume that `foo' returns type `int').
  90. File: cpp.info,  Node: Self-Reference,  Next: Argument Prescan,  Prev: Side Effects,  Up: Macro Pitfalls
  91. Self-Referential Macros
  92. .......................
  93.    A "self-referential" macro is one whose name appears in its
  94. definition.  A special feature of ANSI Standard C is that the
  95. self-reference is not considered a macro call.  It is passed into the
  96. preprocessor output unchanged.
  97.    Let's consider an example:
  98.      #define foo (4 + foo)
  99. where `foo' is also a variable in your program.
  100.    Following the ordinary rules, each reference to `foo' will expand
  101. into `(4 + foo)'; then this will be rescanned and will expand into `(4
  102. + (4 + foo))'; and so on until it causes a fatal error (memory full) in
  103. the preprocessor.
  104.    However, the special rule about self-reference cuts this process
  105. short after one step, at `(4 + foo)'.  Therefore, this macro definition
  106. has the possibly useful effect of causing the program to add 4 to the
  107. value of `foo' wherever `foo' is referred to.
  108.    In most cases, it is a bad idea to take advantage of this feature.  A
  109. person reading the program who sees that `foo' is a variable will not
  110. expect that it is a macro as well.  The reader will come across the
  111. identifier `foo' in the program and think its value should be that of
  112. the variable `foo', whereas in fact the value is four greater.
  113.    The special rule for self-reference applies also to "indirect"
  114. self-reference.  This is the case where a macro X expands to use a
  115. macro `y', and the expansion of `y' refers to the macro `x'.  The
  116. resulting reference to `x' comes indirectly from the expansion of `x',
  117. so it is a self-reference and is not further expanded.  Thus, after
  118.      #define x (4 + y)
  119.      #define y (2 * x)
  120. `x' would expand into `(4 + (2 * x))'.  Clear?
  121.    But suppose `y' is used elsewhere, not from the definition of `x'.
  122. Then the use of `x' in the expansion of `y' is not a self-reference
  123. because `x' is not "in progress".  So it does expand.  However, the
  124. expansion of `x' contains a reference to `y', and that is an indirect
  125. self-reference now because `y' is "in progress".  The result is that
  126. `y' expands to `(2 * (4 + y))'.
  127.    It is not clear that this behavior would ever be useful, but it is
  128. specified by the ANSI C standard, so you may need to understand it.
  129. File: cpp.info,  Node: Argument Prescan,  Next: Cascaded Macros,  Prev: Self-Reference,  Up: Macro Pitfalls
  130. Separate Expansion of Macro Arguments
  131. .....................................
  132.    We have explained that the expansion of a macro, including the
  133. substituted actual arguments, is scanned over again for macro calls to
  134. be expanded.
  135.    What really happens is more subtle: first each actual argument text
  136. is scanned separately for macro calls.  Then the results of this are
  137. substituted into the macro body to produce the macro expansion, and the
  138. macro expansion is scanned again for macros to expand.
  139.    The result is that the actual arguments are scanned *twice* to expand
  140. macro calls in them.
  141.    Most of the time, this has no effect.  If the actual argument
  142. contained any macro calls, they are expanded during the first scan.
  143. The result therefore contains no macro calls, so the second scan does
  144. not change it.  If the actual argument were substituted as given, with
  145. no prescan, the single remaining scan would find the same macro calls
  146. and produce the same results.
  147.    You might expect the double scan to change the results when a
  148. self-referential macro is used in an actual argument of another macro
  149. (*note Self-Reference::.): the self-referential macro would be expanded
  150. once in the first scan, and a second time in the second scan.  But this
  151. is not what happens.  The self-references that do not expand in the
  152. first scan are marked so that they will not expand in the second scan
  153. either.
  154.    The prescan is not done when an argument is stringified or
  155. concatenated.  Thus,
  156.      #define str(s