Comments are an important part of documenting your code.

Adding comments to macros is quite easy, but it has to be done the right way.

This works with both C and C++ compilers.

The easiest way to document macros is to just add comments before or after the macro definition:

// returns the larger of the two arguments
#define MAX(x, y) (x)>(y)?(x):(y)

This works well for small macros, but if you have a larger macro that is spread over several lines, it might be nice to put comments nearer some tricky or crucial bit of code. You can do that by using C-style comments (/**/). The preprocessor treats comments as white space, so comments of the form /* some sort of comment */ are treated as white space.

#define TRANS_TEST(a, b, c) \
{   /* variables to store intermediate results*/ \
    bool aGb = false;\
    bool bGc = false;\
    if (a > b) \
    {\
        aGb = true;
        printf("'a' is larger than 'b'\n");\
    }\
    if (b > c) \
    {\
        bGc = true;
        printf("'b' is larger than 'c'\n");\
    }\
    /* do the transitivity test */ \
    if (aGb &&  bGc) \
    {\
        printf("by transitivity we know 'a' is larger than 'c'\n");\
    }\
}

The above (contrived) example, determines if parameter a is greater than parameter c by using the principle of transitivity.

C style comments were used to document the code. Note the line splicing (\) operator appears at the end of each line.

When this code is compiled, the preprocessor will treat the comment (and any white space surrounding it) as white space.

NOTE: Using C++ single line comments (//)won’t work because everything following the // until the end of the line is considered white space. Even if the macro is spread over several lines using the line splicing (\) operator, the preprocessor turns it into a single line and everything following the // will be considered part of the comment (hence, white space).

#define TRANS_TEST(a, b, c) \
{   // variables to store intermediate results \
    bool aGb = false;\
    bool bGc = false;\
    if (a > b) \
    {\
        aGb = true;
        printf("'a' is larger than 'b'\n");\
    }\
    if (b > c) \
    {\
       bGc = true;
       printf("'b' is larger than 'c'\n");\
    }\
    // do the transitivity test  \
    if (aGb &&  bGc) \
    {\
        printf("by transitivity we know 'a' is larger than 'c'\n");\
    }\
}

In the above example, the C++ single line comment was used. When it is processed by the preprocessor, everything until the end of the line (after all the lines have been spliced together) will be considered a comment. Consequently, the compiler will issue an error because all it will see is:

#define TRANS_TEST(a, b, c) {

The post How to Add Comments to Macros appeared first on Complete, Concrete, Concise.

Behaviour of the #undef directive is the same in both C and C++.

Purpose

It is used to undefine a macro.

A macro is an identifier (or label) followed by replacement text.

There is only a single namespace for macros. A program which redefines an existing macro is considered to be malformed – even though most compilers only generate a warning instead of an error.

Format

All preprocessor directives begin with the # symbol. It must be the first character on the line or the first character on the line following optional white space.

Spaces or tabs are permitted between the # and undef, but not escape characters or other symbols or macros. The preprocessor removes whitespace and concatenates the # and undef together.

The following are valid uses:

#undef my_macro
#    undef      my_macro
     # undef my_macro
# /* comments are whitespace */ undef my_macro

The following are invalid uses:

#define empty_macro
// #empty_macro is not a valid preprocessor directive
#   empty_macro undef my_macro
// #\ is not a valid preprocessor directive
# \t undef my_macro
// #" is not a valid preprocessor directive
# "" undef my_macro

If the specified macro name does not exist, nothing happens.

If the specified macro name exists, its name, parameter list, and replacement text is removed.

Conceptually, macros are stored in a 3 column table:

|------------|----------------|------------------|
| Macro Name | Parameter List | Replacement Text |
|------------|----------------|------------------|
| my_macro   |                | // some text     |
|------------|----------------|------------------|
| macro_2a   | a, b           | ((a)*(b))        |
|------------|----------------|------------------|

When we #undef a macro, we remove it from the table.

A program is malformed if anything other than whitespace (comments count as whitespace) and a newline character follow the macro name.

The post Preprocessor – the #undef Directive appeared first on Complete, Concrete, Concise.

This is the most complicated of the preprocessor directives (a little over 7 pages is devoted to it in the C99 spec and the C++98 spec devotes about 4 pages to it).

Behaviour of the #define directive is the same in both C and C++.

C99 added variable argument macros; the upcoming C++0x standard adds variadic macros, as well.

Purpose

It is used to define a macro.

A macro is an identifier (or label) followed by text.

When the preprocessor encounters the macro in the program it replaces the macro with the text that follows the macro name.

There is no restriction on what may be in the replacement text. The only restriction on the replacement text is that it must be all on the same line as the #define directive (you can use the line continuation character \ to spread your macro over several lines).

A macro may be a simple label or it may be a label with a parameter list. Macros also may use the token pasting (##) operator and stringizing (#) operator to modify their replacement text.

Format

All preprocessor directives begin with the # symbol. It must be the first character on the line or the first character on the line following optional white space.

Spaces or tabs are permitted between the # and define, but not escape characters or other symbols or macros. The preprocessor removes whitespace and concatenates the # and define together.

The following are valid uses:

#define my_macro
# define my_macro
#   define     my_macro

The following are invalid uses:

#define empty_macro
// #empty_macro is not a valid preprocessor directive
# empty_macro define my_macro
// #\ is not a valid preprocessor directive
# \t define my_macro
// #" is not a valid preprocessor directive
# "" define my_macro

Macros with no Parameters

The simplest macros are those which only have a name and some replacement text:

#define my_macro
#define my_other_macro "This is some replacement text."

The first #define creates a macro named my_macro that has no replacement text. This is valid because the replacement text is just nothing (effectively an empty string).

The second define creates a macro named my_other_macro that has "This is some replacement text" as its replacement text (including the quotes).

The replacement text begins at the first non-whitespace character following the macro name and ends at the last non-whitespace character on the line (remember, you can spread your macro over multiple lines by using the \ operator to indicate line continuation).

#define my_macro This is some replacement text
                 ^                           ^
The replacement text begins and ends at the ^ characters.

Every time the preprocessor encounters macro name in the code, it will replace it with the replacement text.

The preprocessor will not replace macro names inside of strings.

#define my_macro "a replacement string"
// this will print a replacement string without quotes
printf(my_macro);
// this will print my_macro because my_macro is inside a string
printf("my_macro");

Macros with Parameters

Macros can also take parameters. Text passed as parameters replaces the parameter placeholder in the replacement text.

#define max (a, b) a > b ? a : b
           ^
The space marks the end of the macro name,
everything following is replacement text.

#define square(a) a*a 

The macro name is square.

The macro parameter is a.

The replacement text is a*a.

Whatever text you pass in the a parameter replaces a in the replacement text.

After the parameters are replaced, that new replacement text replaces square in your code.

After preprocessing, the following source code:

int number = 5;
int c = square(number);

ends up looking like this (this is what the C/C++ compiler sees after preprocessing):

int number = 5;
int c = number * number;

which looks as we would expect it – all occurrences of a have been replaced by the parameter we passed (number).

The preprocessor only performs text replacement, so we can also write the following:

int c = square(12 + 3);

This gets preprocessed into:

int c = 12 + 3 * 12 + 3;

The compiler will parse it as follows (following operator precedence):

int c = 12 + (3 * 12) + 3;

which does not give us the answer we want. Remember, the preprocessor replaces the parameter with the text passed to it. In this case, each occurrence of a is replaced with 12 + 3. This is an example of an “unintended side effect” using a macro. The way to fix this is to ensure each replacement of a is evaluated in its entirety. We do this by adding parentheses around the parameter in the replacement text:

#define square(a) ((a) * (a)) 

Parentheses were also placed around the replacement text to ensure the entire replacement text is evaluated as a whole.

Even with parentheses, it is still possible to get unintended side effects:

int number = 5;
int c = square(number++);

When expanded, this becomes:

int c = ((number++) * (number++));

The side effect is that number is incremented twice and not once as would be assumed from reading square(number++).

Pretty much any text can be passed as a macro parameter – even other macros. You will have difficulty passing a comma (,) since it delimits parameters and the closing parenthesis ()) since it marks the end of the macro parameter list. They can be passed without problem inside of a string.

Macros as Parameters

When a macro is passed as a parameter, the macro will be expanded before replacing the parameter in the replacement text. If the parameter is associated with the stringizing (#) or token pasting (##) operators, then the macro name will be used instead of being expanded.

#define invalid_name "invalid name"
#define error "ERROR - "
#define error_msg(a) error a
.
.
.
printf(error_msg(invalid_name));

In the printf statement, the macro error_msg is passed the macro invalid_name as its parameter. The preprocessor will replace the macro name invalid_name with its replacement text "invalid name". It then processes the replacement text error a by (1) replacing the macro error with its replacement text, (2) replacing parameter a with the previously expanded "invalid name". Once expanded, the compiler sees the following:

printf("ERROR = ""invalid name");

Since there are two juxtaposed strings, they will be concatenated:

printf("ERROR = invalid name");

Passing macros as macro parameters allows you to pass characters you normally wouldn’t be able to.

my_macro defines a simple printf as replacement text. It is obvious that parameter x must be a comma (,) in order for the statement to compile. Trying to pass a comma in the parameter list will fail because it looks to the preprocessor that my_macro is being passed 3 parameters (when it was defined to accept only two):

#define my_macro(x, y) printf("Number passed to macro was %d" x y)
.
.
.
my_macro(,,10);

We can get around this by defining a macro for the comma:

#define comma ,
#define my_macro(x, y) printf("Number passed to macro was %d" x y)
.
.
.
my_macro(comma, 10);

Variadic Macros

In C99 and in the upcoming C++0x versions of the languages, macros can also be defined with a variable number of parameters:

#define my_macro(...)
#define my_other_macro(a, b, ...)

The ellipsis (...) specifies that a variable number of parameters are permitted in place of the ellipsis. The ellipsis must be the last parameter in the macro. (If it is the only parameter in the macro, then it counts as being the last parameter.)

In the replacement text, the parameters taking the place of the ellipsis – including the commas – are referenced using the identifier __VA_ARGS__. Before being assigned to __VA_ARGS__, the preprocessor performs all macro replacements on the arguments:

#define g1 "gyre"
#define g2 "gimble"
#define my_macro(...) printf(__VA_ARGS__)
.
.
.
my_macro("the slithy toves did %s and %s", g1, g2);

my_macro was defined as taking a variable number of arguments. These arguments were then passed to printf. Before passing the variable arguments – referenced as __VA_ARGS__ – to printf, the preprocessor replaces the macros g1 and g2 with their respective replacement texts. This results in the following expansion:

printf("the slithy toves did %s and %s", "gyre", "gimble");

#define my_macro(a, b, ...)
                 ^  ^  ^
                 |  |  |
                 |  |  | everything until the ) replaces
                 |  |  |__VA_ARGS__ in the replacement
                 |  |  |text
                 |  | what is passed here replaces b in the
                 |  | replacement text
                 |what is passed here replaces a in the
                 |replacement text

#define my_macro(a, b, __VA_ARGS__)

Macro re-Processing

After the # and ## operations have been performed, the parameters expanded (if they were macros) and inserted into the replacement text, then the replacement text is processed again looking for macros to replace. However, if any macros are found that have already been replaced, then they are NOT replaced again.

#define comma ,
#define reparse(x, y) x##y
.
.
.
printf("This is a %s" reparse(com, ma) "string");

When reparse(com, ma) is processed, the result is the macro name comma, which is then replaced by the symbol ,

The following:

#define comma reparse(com, ma)
#define reparse(x, y) x##y
reparse(com, ma);

will result in reparse(com, ma) being processed into the macro comma. The macro comma will be re-evaluated and processed into reparse(com, ma). At this point, the preprocessor will stop re-evaluating the macro because it already evaluated the macro reparse earlier in this cycle of evaluations.

Macro Redefinition

All macro names exist in the same namespace, so all macro names must be unique.

If the preprocessor encounters a duplicate macro name, it checks to see if the macro is identical to the original definition – if it is not, the program is considered malformed.

Leading and trailing whitespace are not considered significant. The following are considered identical:

#define my_macro(a) a*a
#define my_macro( a ) a*a
#define my_macro(a) /* comments are */ a*a /* whitespace */

Different parameter names are considered significant. The following are considered different and indicate a malformed program if they appear in the same program:

#define my macro(a) a*a
#define my_macro(b) a*a
#define my_macro(b) b*b

The post Preprocessor – The #define Directive appeared first on Complete, Concrete, Concise.

Macros are a simple text substitution done by the preprocessor. Whenever the macro name is encountered in your code, the preprocessor replaces it with the text to the right of the macro name (plugging in any optional parameters you may have passed).

A macro is composed of three parts:

1. #define – this introduces the macro
2. macro name and optional parameter list. The macro name cannot have any spaces and the parameter list cannot be separated from the macro name with any spaces.
3. text that will replace the macro – everything following the macro name (and optional parameter list), until the end of the line, is what the preprocessor will use to replace the macro name. For long macros, or for better formatting, the macro can be defined over several lines by ending each line with a backslash character (\) and a new line (enter) (extra spaces between the backslash character and new line means the macro ends there – so be careful of extra spaces following the backslash).

Working Examples:

#define my_macro // preprocessor will replace my_macro with this comment.

#define my_macro // when the preprocessor encounters my_macro, \
                    it will replace it with everything on this \
                    line that is to the right of the definition \
                    (which is this comment). Fortunately, \
                    it is possible to spread the line over several \
                    lines by using the backslash character

Not Working Examples:

The following macro won’t compile following expansion (it is supposed to replace the macro with the contents of the parameter list):

The (unhelpful but correct) error message from the compiler (GCC v.4.4.1) is:

The problem is the space between the macro name and the parameter list – there should be none.

Here’s another macro that won’t compile (like the one above, it is supposed to replace the macro with the parameters passed) :

The (unhelpful but correct) from the compiler (GCC v.4.4.1) is:

Again, the problem is a space between the macro name and the parameter list. Removing the space fixes the problem.

The post Compilation Error – Improperly Defined Macro appeared first on Complete, Concrete, Concise.