cpp: Argument Prescan

1 
1 3.10.6 Argument Prescan
1 -----------------------
1 
1 Macro arguments are completely macro-expanded before they are
1 substituted into a macro body, unless they are stringized or pasted with
1 other tokens.  After substitution, the entire macro body, including the
1 substituted arguments, is scanned again for macros to be expanded.  The
1 result is that the arguments are scanned _twice_ to expand macro calls
1 in them.
1 
1    Most of the time, this has no effect.  If the argument contained any
1 macro calls, they are expanded during the first scan.  The result
1 therefore contains no macro calls, so the second scan does not change
1 it.  If the argument were substituted as given, with no prescan, the
1 single remaining scan would find the same macro calls and produce the
1 same results.
1 
1    You might expect the double scan to change the results when a
1 Self-Referential Macros::): the self-referential macro would be expanded
1 once in the first scan, and a second time in the second scan.  However,
1 this is not what happens.  The self-references that do not expand in the
1 first scan are marked so that they will not expand in the second scan
1 either.
1 
1    You might wonder, "Why mention the prescan, if it makes no
1 difference?  And why not skip it and make the preprocessor faster?"  The
1 answer is that the prescan does make a difference in three special
1 cases:
1 
1    * Nested calls to a macro.
1 
1      We say that "nested" calls to a macro occur when a macro's argument
1      contains a call to that very macro.  For example, if 'f' is a macro
1      that expects one argument, 'f (f (1))' is a nested pair of calls to
1      'f'.  The desired expansion is made by expanding 'f (1)' and
1      substituting that into the definition of 'f'.  The prescan causes
1      the expected result to happen.  Without the prescan, 'f (1)' itself
1      would be substituted as an argument, and the inner use of 'f' would
1      appear during the main scan as an indirect self-reference and would
1      not be expanded.
1 
1    * Macros that call other macros that stringize or concatenate.
1 
1      If an argument is stringized or concatenated, the prescan does not
1      occur.  If you _want_ to expand a macro, then stringize or
1      concatenate its expansion, you can do that by causing one macro to
1      call another macro that does the stringizing or concatenation.  For
1      instance, if you have
1 
1           #define AFTERX(x) X_ ## x
1           #define XAFTERX(x) AFTERX(x)
1           #define TABLESIZE 1024
1           #define BUFSIZE TABLESIZE
1 
1      then 'AFTERX(BUFSIZE)' expands to 'X_BUFSIZE', and
1      'XAFTERX(BUFSIZE)' expands to 'X_1024'.  (Not to 'X_TABLESIZE'.
1      Prescan always does a complete expansion.)
1 
1    * Macros used in arguments, whose expansions contain unshielded
1      commas.
1 
1      This can cause a macro expanded on the second scan to be called
1      with the wrong number of arguments.  Here is an example:
1 
1           #define foo  a,b
1           #define bar(x) lose(x)
1           #define lose(x) (1 + (x))
1 
1      We would like 'bar(foo)' to turn into '(1 + (foo))', which would
1      then turn into '(1 + (a,b))'.  Instead, 'bar(foo)' expands into
1      'lose(a,b)', and you get an error because 'lose' requires a single
1      argument.  In this case, the problem is easily solved by the same
1      parentheses that ought to be used to prevent misnesting of
1      arithmetic operations:
1 
1           #define foo (a,b)
1      or
1           #define bar(x) lose((x))
1 
1      The extra pair of parentheses prevents the comma in 'foo''s
1      definition from being interpreted as an argument separator.
1