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