Up until now, you may have thought of the C++ compiler as munching on your source code and spitting out an executable program in one step, but that isn't quite true.

First, the preprocessor makes a pass through your program looking for preprocessor instructions. The output of this preprocessor step is an intermediate file that has all the preprocessor commands expanded. This intermediate file gets passed to the C++ compiler for processing. The output from the C++ compiler is an object file that contains the machine instruction equivalent to your C++ source code. During the final step, a separate program known as the linker combines a set of standard libraries with your object file (or files as we'll see in Chapter 21) to create an executable program. (More on the standard library in the next section of this chapter.)

All preprocessor commands start with a # symbol in column 1 and end with the newline.

In this book, we'll be working with three preprocessor commands:

Each of these preprocessor commands is covered in the following sections.

The C++ standard library consists of functions that are basic enough that almost everyone needs them. It would be silly to force every programmer to have to write them for herself. For example, the I/O functions, which we have been using to read input from the keyboard and write out to the console, are contained in the standard library.

However, C++ requires a prototype declaration for any function you call, whether it's in a library or not (see Chapter 6 if that doesn't make sense to you). Rather than force the programmer to type all these declarations by hand, the library authors created include files that contain little more than prototype declarations. All you have to do is #include the source file that contains the prototypes for the library routines you intend to use.

Take the following simple example. Suppose I had created a library that contains the trigonometric functions sin(), cosin(), tan(), and a whole lot more. I would likely create an include file mytrig with the following contents to go along with my standard library:

// include prototype declarations for my library
double sin(double x);
double cosin(double x);
double tan(double x);
// ...more prototype declarations...

Any program that wanted to make use of one of these math functions would #include that file, enclosing the name of the include file either in brackets or quotes as in

#include <mytrig>

or

#include "mytrig"

Thus, you might write a source file like the following:

// MyProgram - is very intelligent
#include "mytrig"

int main(int nArgc, char* pArguments[])
{
    cout << "The sin of .5 is " << sin(0.5) << endl;
    return 0;
}

The C++ compiler sees the following intermediary file after the preprocessor gets finished expanding the #include:

// MyProgram - is very intelligent
// include prototype declarations for my library
double sin(double x);
double cosin(double x);
double tan(double x);
// ...more prototype declarations...

int main(int nArgc, char* pArguments[])
{

cout << "The sin of .5 is " << sin(0.5) << endl;
    return 0;
}

namespace Mathematics
{
    double log(double x)
    {
        // ...the definition of the function...
    }
}
namespace SystemLog
{
    int log(double x)
    {
        // ...log the value to file...
    }
}

void myFunc(double x)
{
    // invoke the logarithm function...
    double dl = Mathematics::log(x);

    // ...now log it to disk
    SystemLog::log(dl);
}

using double Mathematics::log(double);
void myFunc(double x)
{

// the default is the mathematics version...
    double dl = log(x);

    // ...however, the other version is still accessible by
    // explicitly specifying the namespace
    SystemLog::log(dl);
}

using namespace Mathematics;
void myFunc(double x)
{
    // look in the Mathematics namespace first...
    double dl = log(x);

    // ...however, the other version is still accessible by
    // explicitly specifying the namespace
    SystemLog::log(dl);
}

The preprocessor also allows the programmer to #define expressions that get expanded during the preprocessor step. For example, you can #define a constant to be used throughout the program.

#define TWO_PI 6.2831852

This makes the following statement much easier to understand:

double diameter = TWO_PI * radius;

than the equivalent expression, which is actually what the C++ compiler sees after the preprocessor has replaced TWO_PI with its definition:

double diameter = 6.2831852 * radius;

Another advantage is the ability to #define a constant in one place and use it everywhere. For example, I might include the following #define in an include file:

#define MAX_NAME_LENGTH 512

Throughout the program, I can truncate the names that I read from the keyboard to a common and consistent MAX_NAME_LENGTH. Not only is this easier to read but it also provides a single place in the program to change should I want to increase or decrease the maximum name length that I choose to process.

The preprocessor also allows the program to #define function-like macros with arguments that are expanded when the definition is used:

#define SQUARE(X) X * X

In use, such macro definitions look a lot like functions:

// calculate the area of a circle
double dArea = HALF_PI * SQUARE(dRadius);

Remember that the C++ compiler actually sees the file generated from the expansion of all macros. This can lead to some unexpected results. Consider the following code snippets (these are all taken from the program MacroConfusion, which is included on the CD-ROM):

int nSQ = SQUARE(2);
cout << "SQUARE(2) = " << nSQ << endl;

Reassuringly, this generates the expected output:

SQUARE(2) = 4

However, the following line:

int nSQ = SQUARE(1 + 2);
cout << "SQUARE(1 + 2) = " << nSQ << endl;

generates the surprising result:

SQUARE(1 + 2) = 5

The preprocesor simply replaced X in the macro definition with 1 + 2. What the C++ compiler actually sees is

int nSQ = 1 + 2 * 1 + 2;

Since multiplication has higher precedence than addition, this is turned into 1 + 2 + 2 which, of course, is 5. This confusion could be solved by liberal use of parentheses in the macro definition:

#define SQUARE(X) ((X) * (X))

This version generates the expected:

SQUARE(1 + 2) → ((1 + 2) * (1 + 2)) → 9

However, some unexpected results cannot be fixed no matter how hard you try. Consider the following snippet:

int i = 2;
cout << "i = " << i << endl;
int nSQ = SQUARE(i++);
cout << "SQUARE(i++) = " << nSQ << endl;
cout << "now i = " << i << endl;

This generates the following:

i = 3;
SQUARE(i++) = 9
now i = 5

The value generated by SQUARE is correct but the variable i has been incremented twice. The reason is obvious when you consider the expanded macro:

int i = 3;
nSQ = i++ * i++;

Since autoincrement has precedence, the two i++ operations are performed first. Both return the current value of i, which is 3. These two values are then multiplied together to return the expected value of 9. However, i is then incremented twice to generate a resulting value of 5.

inline int SQUARE(int x) { return x * x; }

const int MAX_NAME_LENGTH = 512;
int szName[MAX_NAME_LENGTH];

constexpr int square(int n1, int n2)
    { return n1 * n1 + 2 * n1 * n2 + n2 * n2;}

#define DC_OR_TERRITORY 0
#define ALABAMA 1
#define ALASKA 2
#define ARKANSAS 3
//...and so on...

// increment the population of ALASKA (they need it)
population[ALASKA]++;

enum STATE {DC_OR_TERRITORY,  // gets 0
            ALABAMA,          // gets 1
            ALASKA,           // gets 2
            ARKANSAS,
           // ...and so on...

enum STATE {DC,
            TERRITORY = 0,
            ALABAMA,
            ALASKA,
            // ...and so on...

enum class STATE {DC,
                   TERRITORIES = 0,
                   ALABAMA,
                   ALASKA,
                   // ...and so on...

STATE s = STATE::ALASKA;

int getPop(STATE s);            // return population
int setPop(STATE s, int pop);   // set the population

int getPop(STATE s)
{
    return population[s];  // not legal
}

int getPop(STATE s)
{
    return population[(int)s];  // is legal
}

The third major class of preprocessor statement is the #if, which is a preprocessor version of the C++ if statement:

#if constexpression
// included if constexpression evaluates to other than 0
#else
// included if constexpression evaluates to 0
#endif

This is known as conditional compilation because the set of statements between the #if and the #else or #endif are included in the compilation only if a condition is true. The constexpression phrase is limited to simple arithmetic and comparison operators. That's okay because anything more than an equality comparison and the occasional addition is rare.

For example, the following is a common use for #if. I can include the following definition within an include file with a name such as LogMessage:

#if DEBUG == 1
inline void logMessage(const char *pMessage)
        { cout << pMessage << endl; }
#else
#define logMessage(X) (0)
#endif

I can now sprinkle error messages throughout my program wherever I need them:

#define DEBUG 1
#include "LogMessage"
void testFunction(char *pArg)
{
    logMessage(pArg);
    // ...function continues...

With DEBUG set to 1, the logMessage() is converted into a call to an inline function that outputs the argument to the display. Once the program is working properly, I can remove the definition of DEBUG. Now the references to logMessage() invoke a macro that does nothing.

A second version of the conditional compilation is the #ifdef (which is pronounced "if def"):

#ifdef DEBUG
// included if DEBUG has been #defined
#else
// included if DEBUG has not been #defined
#endif

There is also an #ifndef (pronounced "if not def"), which is the logical reverse of #ifdef.

C++ defines a set of intrinsic constants, which are shown in Table 10-1. These are constants that C++ thinks are just too cool to be without — and that you would have trouble defining for yourself anyway.

These internal macros are particularly useful when generating error messages. You would think that C++ generates plenty of error messages on its own and doesn't need any more help, but sometimes you want to create your own compiler errors. For you, C++ offers not one, not two, but three options: #error, assert(), and static_assert(). Each of these three mechanisms works slightly differently.

The #error command is a preprocessor directive (as you can tell by the fact that it starts with the # sign). It causes the preprocessor to stop and output a message. Suppose that your program just won't work with anything but standard C++. You could add the following to the beginning of your program:

#if !__cplusplus || !__STDC__
#error This is a standard C++ program.
#endif

Now if someone tries to compile your program with other than a C++ compiler that strictly adheres to the standards, she will get a single neat error message rather than a raft of potentially meaningless error messages from a confused C compiler.

#ifndef __GXX_EXPERIMENTAL_CXX0X__
#error This file requires compiler and library support for the upcoming 
ISO C++ standard, C++0x. This support is currently experimental, and must be 
enabled with the -std=c++0x or -std=gnu++0x compiler options.
#endif

So, if __GXX_EXPERIMENTAL_CXX0X__ is not defined when the preprocessor gets to this point, the preprocessor stops and spits out the three lines telling you to go back and compile with some silly switch set.

Unlike #error, assert() performs its test when the resulting program is executed. For example, suppose that I had written a factorial program that calculates N * (N - 1) * (N - 2) and so on down to 1 for whatever N I pass it. Factorial is only defined for positive integers; passing a negative number to a factorial is always a mistake. To be careful, I should add a test for a nonpositive value at the beginning of the function:

int factorial(int N)

    assert(N > 0);
    // ...program continues...

The program now checks the argument to factorial() each time it is called. At the first sign of negativity, assert() halts the program with a message to the operator that the assertion failed, along with the file and line number.

Liberal use of assert() throughout your program is a good way to detect problems early during development, but constantly testing for errors that have already been found and removed during testing slows the program needlessly. To avoid this, C++ allows the programmer to "remove" the tests when creating the version of the program to be shipped to users: #define the constant NDEBUG (for "not debug mode"). This causes the preprocessor to convert all the calls to assert() in your module to "do nothing's" (universally known as NO-OPs).

The preprocessor cannot perform certain compile-time tests. For example, suppose that your program works properly only if the default integer size is 32 bits. The preprocessor is of no help since it knows nothing about integers or floating points. To address this situation, C++ '09 introduced the keyword static_assert(), which is interpreted by the compiler (rather than the preprocessor). It accepts two arguments: a const expression and a string, as in the following example:

static_assert(sizeof(int) == 4, "int is not 32-bits.");

If the const expression evaluates to 0 or false during compilation, the compiler outputs the string and stops. The static_assert() does not generate any runtime code. Remember, however, that the expression is evaluated at compile time so it cannot contain function calls or references to things that are known only when the program executes.

The typedef keyword allows the programmer to create a shorthand name for a declaration. The careful application of typedef can make the resulting program easier to read. (Note that typedef is not actually a preprocessor command, but it's largely associated with include files and the preprocessor.)

typedef int* IntPtr;
typedef const IntPtr IntConstPtr;

int i;
int *const ptr1 = &i;
IntConstPtr ptr2= ptr1; // ptr1 and ptr2 are the same type

The first two declarations in this snippet give a new name to existing types. Thus, the second declaration declares IntConstPtr to be another name for int const*. When this new type is used in the declaration of ptr2, it has the same effect as the more complicated declaration of ptr1.

Although typedef does not introduce any new capability, it can make some complicated declarations a lot easier to read.