cpp: Concatenation

1 
1 3.5 Concatenation
1 =================
1 
1 It is often useful to merge two tokens into one while expanding macros.
1 This is called "token pasting" or "token concatenation".  The '##'
1 preprocessing operator performs token pasting.  When a macro is
1 expanded, the two tokens on either side of each '##' operator are
1 combined into a single token, which then replaces the '##' and the two
1 original tokens in the macro expansion.  Usually both will be
1 identifiers, or one will be an identifier and the other a preprocessing
1 number.  When pasted, they make a longer identifier.  This isn't the
1 only valid case.  It is also possible to concatenate two numbers (or a
1 number and a name, such as '1.5' and 'e3') into a number.  Also,
1 multi-character operators such as '+=' can be formed by token pasting.
1 
1    However, two tokens that don't together form a valid token cannot be
1 pasted together.  For example, you cannot concatenate 'x' with '+' in
1 either order.  If you try, the preprocessor issues a warning and emits
1 the two tokens.  Whether it puts white space between the tokens is
1 undefined.  It is common to find unnecessary uses of '##' in complex
1 macros.  If you get this warning, it is likely that you can simply
1 remove the '##'.
1 
1    Both the tokens combined by '##' could come from the macro body, but
1 you could just as well write them as one token in the first place.
1 Token pasting is most useful when one or both of the tokens comes from a
1 macro argument.  If either of the tokens next to an '##' is a parameter
1 name, it is replaced by its actual argument before '##' executes.  As
1 with stringizing, the actual argument is not macro-expanded first.  If
1 the argument is empty, that '##' has no effect.
1 
1    Keep in mind that the C preprocessor converts comments to whitespace
1 before macros are even considered.  Therefore, you cannot create a
1 comment by concatenating '/' and '*'.  You can put as much whitespace
1 between '##' and its operands as you like, including comments, and you
1 can put comments in arguments that will be concatenated.  However, it is
1 an error if '##' appears at either end of a macro body.
1 
1    Consider a C program that interprets named commands.  There probably
1 needs to be a table of commands, perhaps an array of structures declared
1 as follows:
1 
1      struct command
1      {
1        char *name;
1        void (*function) (void);
1      };
1 
1      struct command commands[] =
1      {
1        { "quit", quit_command },
1        { "help", help_command },
1        ...
1      };
1 
1    It would be cleaner not to have to give each command name twice, once
1 in the string constant and once in the function name.  A macro which
1 takes the name of a command as an argument can make this unnecessary.
1 The string constant can be created with stringizing, and the function
1 name by concatenating the argument with '_command'.  Here is how it is
1 done:
1 
1      #define COMMAND(NAME)  { #NAME, NAME ## _command }
1 
1      struct command commands[] =
1      {
1        COMMAND (quit),
1        COMMAND (help),
1        ...
1      };
1