Tips and Tricks using the Preprocessor

Tips and tricks using the preprocessor

Problems with function-like macros
- Always write parentheses around the parameters in the definition. Consider the follwing, seemingly simple, macro:
#define TIMES_TWO(x) x * 2
For example TIMES_TWO(4) expands to 4 * 2, which will be evaluated to 8.
- You would expect that TIMES_TWO(4 + 5) would evaluate to 18. It doesn't since the macro simple replaces "x" with
the parameter, as it is written.
- This means that the compiler sees "4 + 5 * 2", which it evaluates to 14.
-The solution is to always include the parameter in parentheses, for example:
#define TIMES_TWO(x) (x) * 2

Problems with function-like macros
Macros (resulting in expressions) should be enclosed in parentheses. Assume that we have the following macro:
#define PLUS1(x) (x) + 1
Here we have correctly placed parentheses around the parameter x. This macro will work in some locations; for
example, the following prints 11, as expected:
printf("%dn", PLUS1(10));
However, in other situations the result might surprise you; the following prints 21, not 22:
printf("%dn", 2 * PLUS1(10));
- Again, this is due to the fact that the preprocessor simply replaces the macro call with a piece of source code. This
is what the compiler sees:
printf("%dn", 2 * (10) + 1);
The solution is to place the entire definition of the macro inside parentheses:
#define PLUS1(x) ((x) + 1)
The preprocessor will expand this as follows, and the result "22", will be printed as expected.
printf("%dn", 2 * ((10) + 1));

Macros and parameters with side effects
- Consider the following macro and a typical way of using it:
#define SQUARE(x) ((x) * (x))
printf("%dn", SQUARE(++i));
The user of the macro probably intended to increase i one step and print the squared value after the increase.
Instead, this is expanded to:
printf("%dn", ((++i) * (++i)));
- The problem is that the side effect will take place on every occasion that a parameter is being used.
- The rule of thumb here is that, if possible, each parameter should be evaluated exactly once.
- If that is not possible this should be documented so that potential users will not be surprised.

Special macro features
Creating a string using the "#" operator
- The "#" operator can be used in function-like macros to convert the parameter into a string.
For example:
#define NAIVE_STR(x) #x
puts(NAIVE_STR(10)); /* This will print "10". */
An example that will not work as expected is:
#define NAME Anders
printf("%s", NAIVE_STR(NAME)); /* Will print NAME. */
- This latter example prints NAME, not what NAME is defined to, which isn't what was intended. So, what can we do
about it? Fortunately, there is a standard solution for this:
#define STR_HELPER(x) #x
#define STR(x) STR_HELPER(x)
- The idea behind this bizarre construction is that when STR(NAME) is expanded it is expanded into
STR_HELPER(NAME), and before STR_HELPER is expanded all object-like macros like NAME are replaced first (as
long as there are macros to replace). When the function-like macro STR_HELPER is invoked the parameter that is
passed to it is Anders.

Joining identifiers using the ## operator
- The "##" operator is used in the definition of preprocessor macros to indicate that we should join together small
fragments into a larger identifier or number or whatever.
For example, assume that we have a collection of variables:
MinTime, MaxTime, TimeCount.
MinSpeed, MaxSpeed, SpeedCount.
We could define a macro, AVERAGE, with one parameter, that could return the average time, speed, or whatever.
Our first, naive, approach could be something like the following:
#define NAIVE_AVERAGE(x)
(((Max##x) - (Min##x)) / (x##Count))
This will work for typical use cases:
NAIVE_AVERAGE(Time);
In this case this would expand to:
return (((MaxTime) - (MinTime)) / (TimeCount));

- However, as with the "#" operator above, when used in the following context this does not work as intended:
#define TIME Time
NAIVE_AVERAGE(TIME)
This, unfortunately, expands to:
return (((MaxTIME) - (MinTIME)) / (TIMECount));
The solution to this is as easy as in the STR case above. You will have to expand the macro in two steps. Typically
you could define a generic macro to glue anything together:
#define GLUE_HELPER(x, y) x##y
#define GLUE(x, y) GLUE_HELPER(x, y)
Now we are ready to use this in our AVERAGE macro:
#define AVERAGE(x)
(((GLUE(Max,x)) - (GLUE(Min,x))) / (GLUE(x,Count)))

Making macros look like statements, the "do {} while(0)" trick
The first step is simple:
- Use object-like macros only for constants.
- Use function-like macros for things that could be placed in a statement of its own, or for expressions that vary over
time.
- The preprocessor only replaces the macro with a piece of source code, so we must ensure that the resulting
program will not become surprised by the semicolon that follows.
For example:
void test()
{
a_function(); /* The semicolon is not part of
A_MACRO(); the macro substitution. */
}

- For macros that consist of one statement this is straight-forward, simply define the macro without a trailing semicolon.
#define DO_ONE() a_function(1,2,3)
- However, what happends if the macro contains two statements, for example two function calls? Why is the following not a
good idea?
#define DO_TWO() first_function(); second_function()
- In a simple context this would work as intended, for example:
DO_TWO();
- This expands to:
first_function(); second_function();
- But what would happend in a context where a single statement is expected, for example:
if (... test something ...)
DO_TWO();
Unfortunately, this expands to:
first_function();
second_function();
- The problem is that only "first_function" will become the body of the "if" statement. The "second_function" will not be part of the
statement, so it will always be called.
- So, what about including the two calls inside braces, then the semicolon the user supplies will simply be a an empty
statement?
#define DO_TWO()
{ first_function(); second_function(); }

- Unfortunately, this still doesn't work as intended even if we expand the context to an "if" "else" clause.
Consider the following example:
DO_TWO();
else
...
- This expands as follows; note the semicolon after the closing brace:
{ first_function(); second_function(); };
else
...
- The body of the "if" consists of two statements (the compound statement inside the braces and the empty statement
consisting only of the semicolon). This is not legal C as there must be exactly one statement between the "if (...)" and
the "else"!
- Here is where an old trick of the trades comes in:
#define DO_TWO()
do { first_function(); second_function(); } while(0)

- The trick is to use a compound statement that expects a semicolon at the end, and there is one such construction in
C, namely "do ... while(...);".
- This version of the macro have the look-and-feel of a normal function. When used inside "if ... else" clauses the
macro will expand to the following correct C code:
do { first_function(); second_function(); } while(0);
else
...
- To conclude, the "do ... while(0)" trick is useful when creating function-like macros with the same look-and-feel as
normal functions.
- The downside is that the macro definition could look unintuitive
- So I recommend that you comment on the purpose of the "do" and "while" so that other people that would read the
code do not have to become puzzled.

Why you should prefer #ifs over #ifdefs
- As we earlier described, both #if and #ifdef can be used to exclude portions of the source code from being
compiled.
#ifdefs
If #ifdefs are used the code looks like the following:
#ifdef MY_COOL_FEATURE
... included if "my cool feature" is used ...
#endif
#ifndef MY_COOL_FEATURE
... excluded if "my cool feature" is used ...
#endif
An application that uses #ifdefs normally doesn't have to have any special handling of configuration variables.

#ifs
When you are using #ifs the preprocessor symbols that are used are normally always defined. The symbols that
correponds to the symbols used by #ifdef are either true or false, which could be represented by the integers 1 and 0,
respectively.
#if MY_COOL_FEATURE
... included if "my cool feature" is used ...
#endif
#if !MY_COOL_FEATURE
... excluded if "my cool feature" is used ...
#endif
Of course, preprocessor symbols could have more states, for example:
#if INTERFACE_VERSION == 0
printf("Hellon");
#elif INTERFACE_VERSION == 1
print_in_color("Hellon", RED);
#elif INTERFACE_VERSION == 2
open_box("Hellon");
#else
#error "Unknown INTERFACE_VERSION"
#endif

- An application that uses this style typically is forced to specify a default value for all configuration variables. This
could, for example, be done in a file, say, "defaults.h". When configuring the application some symbols could be
specified either on the command line, or preferably in a specific configuration header file, say "config.h". This
configuration header file could be left empty if the default configuration should be used.
Example of a defaults.h header file:
/* defaults.h for the application. */
#include "config.h"
/*
* MY_COOL_FEATURE -- True, if my cool feature
* should be used.
*/
#ifndef MY_COOL_FEATURE
#define MY_COOL_FEATURE 0 /* Off by default. */
#endif

#if versus #ifdef which one should we use?
- So far both methods seem fairly equal. If you look at real-world applications you will notice that both are commonly
used. At first glance #ifdefs seem easier to handle but experience has taught me that the #ifs are superior in the long
run.
- #ifdefs don't protect you from misspelled words, #ifs do
- Clearly, an #ifdef can't know whether the identifier is misspelled or not, as all it can tell is whether a certain identifier
is defined at all.
- For example, the following error will go unnoticed through the compilation:
#ifdef MY_COOL_FUTURE /* Should be "FEATURE". */
... Do something important ...
#endif
- On the other hand, most compilers can detect that undefined symbols have been used in an #if directive.

#ifdefs are not future safe
- What will happen if you want to ensure that a property will be configured in a specific way—for example, if you
should support colors— even if the default value should change in the future? Well, unfortunately you cannot do this.
- On the other hand, if you use #ifs to configure an application, you can set a configuration variable to a specific value
to ensure that you are future-safe in case the default value should change.

For #ifdefs, the default value dictates the name:
- If #ifdefs are used to configure an application the default configuration is to not specify any extra symbols.
- For extra features this is straight forward, simply define MY_COOL_FEATURE.
- However, should a feature be removed the name of the identifier often becomes DONT_USE_COLORS.
Double negatives are not really positive, are they?:
- One drawback is that the code becomes harder to read and write as this will introduce double negatives.
- For example, some code should be included for color support:
#ifndef DONT_USE_COLORS
... do something ...
#endif
- It might sound like a detail, but if you are browsing through large portions of code you will sooner or later become confused—well.
- I really do prefer the following:
#if USE_COLORS
... do something ...
#endif
You must know the default value when writing code: Another drawback is that when writing the application you must know (or look up) whether
a feature is enabled by default. In conjunction with the fact that you have no protection against misspelled words, this is an accident waiting to
happen.
Nearly impossible to change the default value for #ifdefs:
- The biggest drawback is that when #ifdefs are used, the application cannot change the default value without changing all #ifdefs all over the
application.
- For #ifs, changing the default value is trivial. All you need to do is to update the file containing the default values.

Migrating from #ifdefs to #ifs
- It is more or less trivial to migrate from #ifdefs to #ifs.
- In addition, you could provide backward compatibility for your old configuration variables.
- First decide that you should name your new configuration variables.
- A variable with a negative name (e.g. DONT_USE_COLORS) should be renamed to a positive form (e.g. USE_COLORS).
- Variables with positive names can keep their names or you could rename them slightly.
- If you keep the name of configuration variables, and the user has defined them as empty (as in "#define MY_COOL_FEATURE") he will get
a compilation error at the first #if that uses that symbol. Simply define them to 1 instead.
- Create a defaults.h header file, as described above, and ensure that all source files include this. (If they do not, you will notice this, as soon
as they use a configuration variable you will get an error since it will be undefined.)
- In the beginning of the header file you could map the old #ifdef names to the new, for example:
/* Old configuration variables, ensure that they still work. */
#ifdef DONT_USE_COLORS
#define USE_COLORS 0
#endif
/* Set the default. */
#ifndef USE_COLORS
#define USE_COLORS 1
#endif
- Then rename all occurences of #ifdefs to #ifs in all source files, accordingly:
From: To:
#ifdef MY_COOL_FEATURE #if MY_COOL_FEATURE
#ifndef MY_COOL_FEATURE #if !MY_COOL_FEATURE
#ifdef DONT_USE_COLORS #if !USE_COLORS
#ifndef DONT_USE_COLORS #if USE_COLORS
- The end result is an application where all configuration variables are defined in one central location, together with the current default setting.

Tips and Tricks using the Preprocessor

More Related Content

Similar to Tips and Tricks using the Preprocessor (20)

Recently uploaded (20)

Tips and Tricks using the Preprocessor