PRE05-A. Understand macro replacement when concatenating tokens

It is often useful to merge two tokens into one while expanding macros. This is called token pasting or token concatenation. The ## preprocessing operator performs token pasting. When a macro is expanded, the two tokens on either side of each ## operator are combined into a single token, which replaces the ## and the two original tokens in the macro expansion [[FSF 05]].

Token pasting is most useful when one or both of the tokens comes from a macro argument. If either of the tokens next to an ## is a parameter name, it is replaced by its actual argument before ## executes. The actual argument is not macro-expanded first.

The following definition for static_assert() from [[DCL03-A. Use a static assertion to test the value of a constant expression]] uses the JOIN() macro to concatenate the token assertion_failed_at_line_ with the value of __LINE__.

#define JOIN(x, y) x ## y

#define static_assert(e, s) \
  typedef char JOIN(assertion_failed_at_line_, __LINE__) [(e) ? 1 : -1]

__LINE__ is a predefined macro names which expands to an integer constant representing the presumed line number of the current source line within the current source file [[ISO/IEC 9899-1999]].

However, the __LINE__ is not expanded, and the character array is subsequently named assertion_failed_at_line___LINE__. To get the macro to expand, a second level of indirection has to be added as in the following example:

#define JOIN(x, y) JOIN_AGAIN(x, y)
#define JOIN_AGAIN(x, y) x ## y

JOIN(x, y) calls JOIN_AGAIN(x, y) so that, if x or y is a macro, they are expanded before the ## operator pastes them together.

Note also that macro parameters cannot be individually parenthesized when concatenating tokens using the ## operator, converting macro parameters to strings using the # operator, or concatenating adjacent string literals. This is an exception to [[PRE01-A. Use parentheses within macros around parameter names]].

Risk Assessment

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

References

[[FSF 05]] Section 3.5, "Concatenation"
[[ISO/IEC 9899-1999]] Section 6.10.3, "Macro replacement," Section 6.10.3.3, "The ## operator," and Section 6.10.3.4, "Rescanning and further replacement," and Section 6.10.8, "Predefined macro names"
[Saks 08] Dan Saks, Stephen C. Dewhurst. Presentation. Sooner Rather Than Later: Static Programming Techniques for C++.

PRE04-A. Do not reuse a standard header file name      01. Preprocessor (PRE)       PRE06-A. Enclose header file in an inclusion guard