C++ Tutorial – 27 – Preprocessor I

The preprocessor is a program invoked by the compiler that modifies the source code before the actual compilation takes place. This modification is done according to the preprocessor directives that are included in the source files. The directives are easily distinguished from normal programming code in that they all start with a hash sign (#). They must always appear as the first non-whitespace character on a line. Below is a table of the preprocessor directives available in C++ and their function.

Including source files

The #include directive inserts the contents of a file into the current source file. If the filename is enclosed between angle brackets the compiler will search for the file in the default directory where it is configured to look for the standard header files.

#include <iostream> // search default directory

If instead the filename is specified between double-quotes, the compiler will first search for the file in the same directory as the source file and in case it is not there it will then search among the standard header files.

#include "MyFile" // search current, then default

Double quotes can also be used to specify an absolute or relative path to the file.

#include "C:\MyFile" // absolute path
#include "..\MyFile" // relative path

The angle bracket form of #include is normally used for programmer defined headers, while the quoted form is used for standard library headers.

Defining macros

Another important directive is #define, which is used to create macros. After the directive, the name of the macro is specified followed by what it will be replaced by.

#define MACRO 0 // macro definition

The preprocessor will go through and change any occurrences of the macro with whatever comes after it in its definition until the end of the line.

int x = MACRO; // x = 0

By convention, macros should be named in uppercase letters with each word separated by an underscore. That way they are easy to spot when reading the source code.

Undefining macros

A #define directive should not be used to directly override a previously defined macro. Doing so will give a compiler warning. In order to change a macro it first needs to be undefined using the #undef directive before it is redefined. Note that attempting to undefine a macro that is not currently defined will not generate a warning.

#undef MACRO // macro undefine
#undef MACRO // allowed

Macro functions

A macro can be made to take arguments. This allows them to define compile-time functions. For example, the macro function below evaluates to the largest of its two arguments.

#define MAX(a,b) a>b ? a:b

The macro function is called just as if it was a regular C++ function. Keep in mind that for this kind of function to work the arguments must be known at compile-time.

int x = MAX(MACRO, 1); // evaluates to 1

Line-break

To break a macro function across several lines the backslash character can be used. This will escape the newline character that marks the end of a preprocessor directive. There must not be any whitespace after the backslash.

#define MAX(a,b)  \
            a>b ? \
            a:b

Avoid using macros

Although #define directives can be powerful, they tend to make the code more difficult to read and debug. Macros should therefore only be used when they are absolutely necessary. C++ code such as constant variables, enums and inline functions can often accomplish the same goal more efficiently and safely than #define directives can.

#define DEBUG 0
const bool DEBUG = 0;
 
#define FORWARD 1
#define STOP 0
#define BACKWARD -1
enum DIR { FORWARD = 1, STOP = 0, BACKWARD = -1 };
 
#define MAX(a,b) a>b ? a:b
inline int MAX(int a, int b) { return a>b ? a:b; }