cpp: Object-like Macros

1 
1 3.1 Object-like Macros
1 ======================
1 
1 An "object-like macro" is a simple identifier which will be replaced by
1 a code fragment.  It is called object-like because it looks like a data
1 object in code that uses it.  They are most commonly used to give
1 symbolic names to numeric constants.
1 
1    You create macros with the '#define' directive.  '#define' is
1 followed by the name of the macro and then the token sequence it should
1 be an abbreviation for, which is variously referred to as the macro's
1 "body", "expansion" or "replacement list".  For example,
1 
1      #define BUFFER_SIZE 1024
1 
1 defines a macro named 'BUFFER_SIZE' as an abbreviation for the token
1 '1024'.  If somewhere after this '#define' directive there comes a C
1 statement of the form
1 
1      foo = (char *) malloc (BUFFER_SIZE);
1 
1 then the C preprocessor will recognize and "expand" the macro
1 'BUFFER_SIZE'.  The C compiler will see the same tokens as it would if
1 you had written
1 
1      foo = (char *) malloc (1024);
1 
1    By convention, macro names are written in uppercase.  Programs are
1 easier to read when it is possible to tell at a glance which names are
1 macros.
1 
1    The macro's body ends at the end of the '#define' line.  You may
1 continue the definition onto multiple lines, if necessary, using
1 backslash-newline.  When the macro is expanded, however, it will all
1 come out on one line.  For example,
1 
1      #define NUMBERS 1, \
1                      2, \
1                      3
1      int x[] = { NUMBERS };
1           ==> int x[] = { 1, 2, 3 };
1 
1 The most common visible consequence of this is surprising line numbers
1 in error messages.
1 
1    There is no restriction on what can go in a macro body provided it
1 decomposes into valid preprocessing tokens.  Parentheses need not
1 balance, and the body need not resemble valid C code.  (If it does not,
1 you may get error messages from the C compiler when you use the macro.)
1 
1    The C preprocessor scans your program sequentially.  Macro
1 definitions take effect at the place you write them.  Therefore, the
1 following input to the C preprocessor
1 
1      foo = X;
1      #define X 4
1      bar = X;
1 
1 produces
1 
1      foo = X;
1      bar = 4;
1 
1    When the preprocessor expands a macro name, the macro's expansion
1 replaces the macro invocation, then the expansion is examined for more
1 macros to expand.  For example,
1 
1      #define TABLESIZE BUFSIZE
1      #define BUFSIZE 1024
1      TABLESIZE
1           ==> BUFSIZE
1           ==> 1024
1 
1 'TABLESIZE' is expanded first to produce 'BUFSIZE', then that macro is
1 expanded to produce the final result, '1024'.
1 
1    Notice that 'BUFSIZE' was not defined when 'TABLESIZE' was defined.
1 The '#define' for 'TABLESIZE' uses exactly the expansion you specify--in
1 this case, 'BUFSIZE'--and does not check to see whether it too contains
1 macro names.  Only when you _use_ 'TABLESIZE' is the result of its
1 expansion scanned for more macro names.
1 
1    This makes a difference if you change the definition of 'BUFSIZE' at
1 some point in the source file.  'TABLESIZE', defined as shown, will
1 always expand using the definition of 'BUFSIZE' that is currently in
1 effect:
1 
1      #define BUFSIZE 1020
1      #define TABLESIZE BUFSIZE
1      #undef BUFSIZE
1      #define BUFSIZE 37
1 
1 Now 'TABLESIZE' expands (in two stages) to '37'.
1 
1    If the expansion of a macro contains its own name, either directly or
1 via intermediate macros, it is not expanded again when the expansion is
11 examined for more macros.  This prevents infinite recursion.  ⇒
 Self-Referential Macros, for the precise details.
1