Preprocessor Directives: Example
Preprocessor Directives: Example
EXAMPLE
C+ + By
6
Preproc essor
Direc tives
As you might recall from Chapter 2, What Is a Program?, the C++
compiler routes your programs through a preprocessor before it
compiles them. The preprocessor can be called a pre-compiler
because it preprocesses and prepares your source code for compil-
ing before your compiler receives it.
Because this preprocess is so important to C++, you should
familiarize yourself with it before learning more specialized com-
mands in the language. Regular C++ commands do not affect the
preprocessor. You must supply special non-C++ commands, called
preprocessor directives, to control the preprocessor. These directives
enable you, for example, to modify your source code before the code
reaches the compiler. To teach you about the C++ preprocessor, this
chapter
o Defines preprocessor directives
o Introduces the #i ncl ude preprocessor directive
o Introduces the #def i ne preprocessor directive
o Provides examples of both
Chapter 6 o Preprocessor D irectives
114
Almost every proper C++ program contains preprocessor di-
rectives. This chapter teaches you the two most common: #i ncl ude
and #def i ne.
Understanding Preproc essor
Direc tives
Preprocessor directives are commands that you supply to the
preprocessor. All preprocessor directives begin with a pound sign
(#). Never put a semicolon at the end of preprocessor directives,
because they are preprocessor commands and not C++ commands.
Preprocessor directives typically begin in the first column of your
source program. They can begin in any column, of course, but you
should try to be consistent with the standard practice and start them
in the first column wherever they appear. Figure 6.1 illustrates a
program that contains three preprocessor directives.
/ / Fi l ename: C6PRE. CPP
/ / C++ pr ogr amt hat demonst r at es pr epr ocessor di r ect i ves.
#i ncl ude <i ost r eam. h>
#def i ne AGE 28
#def i ne MESSAGE Hel l o, wor l d
mai n( )
{
i nt i = 10, age; / / i i s assi gned a val ue at decl ar at i on
/ / age i s st i l l UNDEFI NED
age = 5; / / Def i nes t he var i abl e, age, as f i ve.
i = i * AGE; / / AGE i s not t he same as t he var i abl e, age.
cout << i << << age << << AGE << \ n; / / 280 5 28
cout << MESSAGE; / / Pr i nt s Hel l o wor l d.
r et ur n 0;
}
Figure 6.1. Program containing three preprocessor directives.
Preprocessor
directives
115
EXAMPLE
C+ + By
Preprocessor directives cause your C++ preprocessor to change
your source code, but these changes last only as long as the compi-
lation. When you look at your source code again, the preprocessor
is finished with your file and its changes are no longer in the file.
Your preprocessor does not in any way compile your program or
change your actual C++ commands. This concept confuses some
beginning C++ students, but just remember that your program has
yet to be compiled when your preprocessor directives execute.
It has been said that a preprocessor is nothing more than a text-
editor on your program. This analogy holds true throughout this
chapter.
The #i ncl ude Direc tive
The #i ncl ude preprocessor directive merges a disk file into your
source program. Remember that a preprocessor directive does
nothing more than a word processing command does to your
program; word processors also are capable of file merging. The
format of the #i ncl ude preprocessor directive follows:
#i ncl ude <f i l ename>
or
#i ncl ude f i l ename
In the #i ncl ude directive, the f i l ename must be an ASCII text file
(as your source file must be) located somewhere on a disk. To better
illustrate this rule, it might help to leave C++ for just a moment. The
following example shows the contents of two files on disk. One is
called OUTSIDE and the other is called INSIDE.
These are the contents of the OUTSIDE file:
Now i s t he t i me f or al l good men
#i ncl ude <I NSI DE>
t o come t o t he ai d of t hei r count r y.
Preprocessor
di recti ves
temporari l y change
your source code.
Chapter 6 o Preprocessor D irectives
116
The INSIDE file contains the following:
A qui ck br own f ox j umped
over t he l azy dog.
Assume you can run the OUTSIDE file through the C++
preprocessor, which finds the #i ncl ude directive and replaces it with
the entire file called INSIDE. In other words, the C++ preprocessor
directive merges the INSIDE file into the OUTSIDE fileat the
#i ncl ude locationand OUTSIDE expands to include the merged
text. After the preprocessing ends, OUTSIDE looks like this:
Now i s t he t i me f or al l good men
A qui ck br own f ox j umped
over t he l azy dog.
t o come t o t he ai d of t hei r count r y.
The INSIDE file remains on disk in its original form. Only the
file containing the #i ncl ude directive is changed. This change is only
temporary; that is, OUTSIDE is expanded by the included file only
for as long as it takes to compile the program.
A few real-life examples might help, because the OUTSIDE and
INSIDE files are not C++ programs. You might want to include a file
containing common code that you frequently use. Suppose you
print your name and address quite often. You can type the following
few lines of code in every program that prints your name and
address:
cout << Kel l y J ane Pet er son\ n;
cout << Apar t ment #217\ n;
cout << 4323 East Skel l y Dr i ve\ n;
cout << New Yor k, New Yor k\ n;
cout << 10012\ n;
Instead of having to retype the same five lines again and again,
you type them once and save them in a file called MYADD.C. From
then on, you only have to type the single line:
#i ncl ude <myadd. c>
117
EXAMPLE
C+ + By
This not only saves typing, but it also maintains consistency
and accuracy. (Sometimes this kind of repeated text is known as a
boilerplate.)
You usually can use angled brackets, <>, or double quotation
marks, , around the included filename with the same results. The
angled brackets tell the preprocessor to look for the include file in a
default include directory, set up by your compiler. The double
quotation marks tell the preprocessor first to look for the include file
in the directory where the source code is stored, and then, to look for
it in the systems include directory.
Most of the time, you do see angled brackets around the
included filename. If you want to include sections of code in other
programs, be sure to store that code in the systems include directory
(if you use angled brackets).
Even though #i ncl ude works well for inserted source code,
there are other ways to include common source code that are more
efficient. You learn about one technique, called writing external
functions, in Chapter 16, Writing C++ Functions.
This source code #i ncl ude example serves well to explain what
the #i ncl ude preprocessor directive does. Despite this fact, #i ncl ude
seldom is used to include source code text, but is more often used to
include special system files called header files. These system files
help C++ interpret the many built-in functions that you use. Your
C++ compiler comes with its own header files. When you (or your
system administrator) installed your C++ compiler, these header
files were automatically stored on your hard drive in the systems
include directory. Their filenames always end in .h to differentiate
them from regular C++ source code.
The most common header file is named iostream.h. This file
gives your C++ compiler needed information about the built-in cout
and ci n operators, as well as other useful built-in routines that
perform input and output. The name iostream.h stands for input/
output stream header.
At this point, you dont have to understand the iostream.h file.
You only have to place this file before mai n( ) in every program you
write. It is rare that a C++ program does not need the iostream.h file.
Even when the file is not needed, including it does no harm. Your
programs can work without iostream.h as long as they do not use
The #i ncl ude
di recti ve i s most
often used for
system header fi l es.
Chapter 6 o Preprocessor D irectives
118
an input or output operator defined there. Nevertheless, your
programs are more accurate and hidden errors come to the surface
much faster if you include this file.
Throughout this book, whenever a new built-in function is
described, the functions matching header file is included. Because
almost every C++ program you write includes a cout to print to the
screen, almost every program contains the following line:
Include the built-in C++ header file called iostream.h.
#i ncl ude <i ost r eam. h>
In the last chapter, you saw the st r cpy( ) function. Its header file
is called string.h. Therefore, if you write a program that contains
st r cpy( ) , include its matching header file at the same time you
include <i ost r eam. h>. These appear on separate lines, such as:
#i ncl ude <i ost r eam. h>
#i ncl ude <st r i ng. h>
The order of your include files does not matter as long as you
include the files before the functions that need them. Most C++
programmers include all their needed header files before mai n( ) .
These header files are simply text files. If you like, find a header
file such as stdio.h on your hard drive and look at it. The file might
seem complex at this point, but there is nothing hidden about it.
Dont change the header file in any way while looking at it. If you do,
you might have to reload your compiler to restore the file.
Examples
1. The following program is short. It includes the name-and-
address printing routine described earlier. After printing the
name and address, it ends.
/ / Fi l ename: C6I NC1. CPP
/ / I l l ust r at es t he #i ncl ude pr epr ocessor di r ect i ves.
#i ncl ude <i ost r eam. h>
119
EXAMPLE
C+ + By
mai n( )
{
#i ncl ude myadd. c
r et ur n 0;
}
The double quotation marks are used because the file called
MYADD.C is stored in the same directory as the source file.
Remember that if you type this program into your computer
(after typing and saving the MYADD.C file) and then com-
pile your program, the MYADD.C file is included only as
long as it takes to compile the program. Your compiler does
not see this file. Your compiler acts as if you have typed the
following:
/ / Fi l ename: C6I NCL1. CPP
/ / I l l ust r at es t he #i ncl ude pr epr ocessor di r ect i ve.
#i ncl ude <i ost r eam. h>
mai n( )
{
cout ( Kel l y J ane Pet er son\ n;
cout ( Apar t ment #217\ n;
cout ( 4323 East Skel l y Dr i ve\ n;
cout ( New Yor k, New Yor k\ n;
cout ( 10012\ n;
r et ur n 0;
}
This explains what is meant by a preprocessor: The changes
are made to your source code before its compiled. Your
original source code is restored as soon as the compile is
finished. When you look at your program again, it appears
as originally typed, with the #i ncl ude statement.
2. The following program copies a message into a character
array and prints it to the screen. Because the cout and
st r cpy( ) built-in functions are used, both of their header files
are included.
Chapter 6 o Preprocessor D irectives
120
The #def i ne
di recti ve repl aces
every occurrence of
a fi rst argument wi th
a second argument.
/ / Fi l ename: C6I NCL3. CPP
/ / Uses t wo header f i l es.
#i ncl ude <i ost r eam. h>
#i ncl ude <st r i ng. h>
mai n( )
{
char message[ 20] ;
st r cpy( message, Thi s i s f un! ) ;
cout << message;
r et ur n 0;
}
The #def i ne Direc tive
The #def i ne preprocessor directive is used in C++ program-
ming, although not nearly as frequently as it is in C. Due to the
const keyword (in C++) that enables you to define variables as
constants, #def i ne is not used as much in C++. Nevertheless, #def i ne
is useful for compatibility to C programs you are converting to C++.
The #def i ne directive might seem strange at first, but it is similar to
a search-and-replace command on a word processor. The format of
#def i ne follows:
#def i ne ARGUMENT1 ar gument 2
where ARGUMENT1 is a single word containing no spaces. Use the same
naming rules for the #def i ne statements first argument as for vari-
ables (see Chapter 4, Variables and Literals). For the first argu-
ment, it is traditional to use uppercase lettersone of the only uses
of uppercase in the entire C++ language. At least one space separates
ARGUMENT1 from ar gument 2. The ar gument 2 can be any character, word,
or phrase; it also can contain spaces or anything else you can type on
the keyboard. Because #def i ne is a preprocessor directive and not a
C++ command, do not put a semicolon at the end of its expression.
The #def i ne preprocessor directive replaces the occurrence
of ARGUMENT1 everywhere in your program with the contents of
121
EXAMPLE
C+ + By
ar gument 2. In most cases, the #def i ne directive should go before mai n( )
(along with any #i ncl ude directives). Look at the following #def i ne
directive:
Define the AGELI MI T literal to 21.
#def i ne AGELI MI T 21
If your program includes one or more occurrences of the term
AGELI MI T, the preprocessor replaces every one of them with the
number 21. The compiler then reacts as if you actually had typed 21
rather than AGELI MI T, because the preprocessor changes all occur-
rences of AGELI MI T to 21 before your compiler reads the source code.
But, again, the change is only temporary. After your program is
compiled, you see it as you originally typed it, with #def i ne and
AGELI MI T still intact.
AGELI MI T is not a variable, because variables are declared and
assigned values only at the time when your program is compiled
and run. The preprocessor changes your source file before the time
it is compiled.
You might wonder why you would ever have to go to this much
trouble. If you want 21 everywhere AGELI MI T occurs, you could type
21 to begin with! But the advantage of using #def i ne rather than
literals is that if the age limit ever changes (perhaps to 18), you have
to change only one line in the program, not every single occurrence
of the literal 21.
Because #def i ne enables you easily to define and change liter-
als, the replaced arguments of the #def i ne directive are sometimes
called defined literals. (C programmers say that #def i ne defines
constants, but C++ programmers rarely use the word constant
unless they are discussing the use of const .) You can define any type
of literal, including string literals. The following program contains
a defined string literal that replaces a string in two places.
/ / Fi l ename: C6DEF1. CPP
/ / Def i nes a st r i ng l i t er al and uses i t t wi ce.
#i ncl ude <i ost r eam. h>
#def i ne MYNAME Phi l War d
mai n( )
The #def i ne
di recti ve creates
defi ned l i teral s.
Chapter 6 o Preprocessor D irectives
122
{
char name[ ] =MYNAME;
cout << My name i s << name << \ n; / / Pr i nt s t he ar r ay.
cout << My name i s << MYNAME << \ n; / / Pr i nt s t he
/ / def i ned l i t er al .
r et ur n 0;
}
The first argument of #def i ne is in uppercase to distinguish it
from variable names in the program. Variables are usually typed in
lowercase. Although your preprocessor and compiler will not con-
fuse the two, other users who look at your program can more quickly
scan through and tell which items are defined literals and which are
not. They will know when they see an uppercase word (if you follow
the recommended standard for this first #def i ne argument) to look at
the top of the program for its actual defined value.
The fact that defined literals are not variables is even more clear
in the following program. This program prints five values. Try to
guess what those five values are before you look at the answer
following the program.
/ / Fi l ename: C6DEF2. CPP
/ / I l l ust r at es t hat #def i ne l i t er al s ar e not var i abl es.
#i ncl ude <i ost r eam. h>
#def i ne X1 b+c
#def i ne X2 X1 + X1
#def i ne X3 X2 * c + X1 - d
#def i ne X4 2 * X1 + 3 * X2 + 4 * X3
mai n( )
{
i nt b = 2; / / Decl ar es and i ni t i al i zes f our var i abl es.
i nt c = 3;
i nt d = 4;
i nt e = X4;
/ / Pr i nt s t he val ues.
cout << e << , << X1 << , << X2;
cout << , << X3 << , << X4 << \ n;
r et ur n 0;
}
123
EXAMPLE
C+ + By
The output from this program is
44 5 10 17 44
If you treated X1, X2, X3, and X4 as variables, you would not
receive the correct answers. X1 through X4 are not variables; they are
defined literals. Before your program is compiled, the preprocessor
reads the first line and changes every occurrence of X1 to b+c. This
occurs before the next #def i ne is processed. Therefore, after the first
#def i ne, the source code looks like this:
/ / Fi l ename: C6DEF2. CPP
/ / I l l ust r at es t hat #def i ne l i t er al s ar e not var i abl es.
#i ncl ude <i ost r eam. h>
#def i ne X2 b+c + b+c
#def i ne X3 X2 * c + b+c - d
#def i ne X4 2 * b+c + 3 * X2 + 4 * X3
mai n( )
{
i nt b=2; / / Decl ar es and i ni t i al i zes f our var i abl es.
i nt c=3;
i nt d=4;
i nt e=X4;
/ / Pr i nt s t he val ues.
cout << e << , << b+c << , << X2;
cout << , << X3 << , << X4 << \ n;
r et ur n 0;
}
After the first #def i ne finishes, the second one takes over and
changes every occurrence of X2 to b+c + b+c. Your source code at that
point becomes:
/ / Fi l ename: C6DEF2. CPP
/ / I l l ust r at es t hat #def i ne l i t er al s ar e not var i abl es.
#i ncl ude <i ost r eam. h>
Chapter 6 o Preprocessor D irectives
124
#def i ne X3 b+c + b+c * c + b+c - d
#def i ne X4 2 * b+c + 3 * b+c + b+c + 4 * X3
mai n( )
{
i nt b=2; / / Decl ar es and i ni t i al i zes f our var i abl es.
i nt c=3;
i nt d=4;
i nt e=X4;
/ / Pr i nt s t he val ues.
cout << e << , << b+c << , << b+c + b+c;
cout << , << X3 << , << X4 << \ n;
r et ur n 0;
}
After the second #def i ne finishes, the third one takes over and
changes every occurrence of X3 to b+c +b+c * c +b+c - d. Your source
code then becomes:
/ / Fi l ename: C6DEF2. CPP
/ / I l l ust r at es t hat #def i ne l i t er al s ar e not var i abl es.
#i ncl ude <i ost r eam. h>
#def i ne X4 2 * b+c + 3 * b+c + b+c + 4 * b+c + b+c * c + b+c - d
mai n( )
{
i nt b=2; / / Decl ar es and i ni t i al i zes f our var i abl es.
i nt c=3;
i nt d=4;
i nt e=X4;
/ / Pr i nt s t he val ues.
cout << e << , << b+c << , << b+c + b+c;
cout << , << b+c + b+c * c + b+c - d
<< , << X4 << \ n;
r et ur n 0;
}
125
EXAMPLE
C+ + By
The source code is growing rapidly! After the third #def i ne
finishes, the fourth and last one takes over and changes every occur-
rence of X4 to 2 * b+c + 3 * b+c + b+c + 4 * b+c + b+c * c +b+c - d.
Your source code at this last point becomes:
/ / Fi l ename: C6DEF2. CPP
/ / I l l ust r at es t hat #def i ne l i t er al s ar e not var i abl es.
#i ncl ude <i ost r eam. h>
mai n( )
{
i nt b=2; / / Decl ar es and i ni t i al i zes f our var i abl es.
i nt c=3;
i nt d=4;
i nt e=2 * b+c + 3 * b+c + b+c + 4 * b+c + b+c * c + b+c - d;
/ / Pr i nt s t he val ues.
cout << e << , << b+c << , << b+c + b+c;
cout << , << b+c + b+c * c + b+c - d
<< , << 2 * b+c + 3 * b+c + b+c + 4 * b+c +
b+c * c + b+c - d << \ n;
r et ur n 0;
}
This is what your compiler actually reads. You did not type this
complete listing; you typed the original listing (shown first). The
preprocessor expanded your source code into this longer form, just
as if you had typed it this way.
This is an extreme example, but it serves to illustrate how
#def i ne works on your source code and doesnt define any variables.
The #def i ne behaves like a word processors search-and-replace
command. Due to #def i nes behavior, you can even rewrite the C++
language!
If you are used to BASIC, you might be more comfortable
typing PRI NT rather than C++s cout when you want to print on-
screen. If so, the following #def i ne statement,
#def i ne PRI NT cout
enables you to print in C++ with these statements:
Chapter 6 o Preprocessor D irectives
126
PRI NT << Thi s i s a new pr i nt i ng t echni que\ n;
PRI NT << I coul d have used cout i nst ead. \ n;
This works because by the time your compiler reads the pro-
gram, it reads only the following:
cout << Thi s i s a new pr i nt i ng t echni que\ n;
cout << I coul d have used cout i nst ead. \ n;
In the next chapter, Simple Input/Output, you learn about
two functions sometimes used for input and output called pr i nt f ( )
and scanf ( ) . You can just as easily redefine function names using
#def i ne as you did with cout .
Also, remember that you cannot replace a defined literal if it
resides in another string literal. For example, you cannot use the
following #def i ne statement:
#def i ne AGE
to replace information in this cout :
cout << AGE;
because AGE is a string literal, and it prints literally just as it appears
inside the double quotation marks. The preprocessor can replace
only defined literals that do not appear in quotation marks.
Do Not Overdo #def i ne
Many early C programmers enjoyed redefining parts of the
language to suit whatever they were used to in another lan-
guage. The cout to PRI NT example was only one example of this.
You can redefine virtually any C++ statement or function to
look any way you like.
There is a danger to this, however, so be wary of using #def i ne
for this purpose. Your redefining the language becomes con-
fusing to others who modify your program later. Also, as you
become more familiar with C++, you will naturally use the true
127
EXAMPLE
C+ + By
C++ language more and more. When you are comfortable with
C++, older programs that you redefined will be confusing
even to you!
If you are programming in C++, use the language conventions
that C++ provides. Shy away from trying to redefine com-
mands in the language. Think of the #def i ne directive as a way
to define numeric and string literals. If those literals ever
change, you have to change only one line in your program.
Just say no to any temptation to redefine commands and
built-in functions. Better yet, modify any older C code that uses
#def i ne, and replace the #def i ne preprocessor directive with the
more useful const command.
Examples
1. Suppose you want to keep track of your companys target
sales amount of $55,000.00. That target amount has not
changed for the previous two years. Because it probably will
not change soon (sales are flat), you decide to start using a
defined literal to represent this target amount. Then, if target
sales do change, you just have to change the amount on the
#def i ne line to:
#def i ne TARGETSALES 55000. 00
which defines a floating-point literal. You can then assign
TARGETSALES to floating-point variables and print its value, just
as if you had typed 55000.00 throughout your program, as
these lines show:
amt = TARGETSALES
cout << TARGETSALES;
2. If you find yourself defining the same literals in many
programs, file the literals on disk and include them. Then,
you dont have to type your defined literals at the beginning
Chapter 6 o Preprocessor D irectives
128
of every program. If you store these literals in a file called
MYDEFS.C in your programs directory, you can include the
file with the following #i ncl ude statement:
#i ncl ude mydef s. c
(To use angled brackets, you have to store the file in your
systems include directory.)
3. Defined literals are appropriate for array sizes. For example,
suppose you declare an array for a customers name. When
you write the program, you know you dont have a cus-
tomer whose name is longer than 22 characters (including
the null). Therefore, you can do this:
#def i ne CNMLENGTH 22
When you define the array, you can use this:
char cust _name[ CNMLENGTH]
Other statements that need the array size also can use
CNMLENGTH.
4. Many C++ programmers define a list of error messages.
Once they define the messages with an easy-to-remember
name, they can print those literals if an error occurs and still
maintain consistency in their programs. The following error
messages (or a similar form) often appear at the beginning of
C++ programs.
#def i ne DI SKERR Your di sk dr i ve seems not t o be wor ki ng
#def i ne PRNTERR Your pr i nt er i s not r espondi ng
#def i ne AGEERR You cannot ent er an age t hat smal l
#def i ne NAMEERR You must ent er a f ul l name
Review Questions
The answers to the review questions are in Appendix B.
1. True or false: You can define variables with the preprocessor
directives.
129
EXAMPLE
C+ + By
2. Which preprocessor directive merges another file into your
program?
3. Which preprocessor directive defines literals throughout
your program?
4. True or false: You can define character, string, integer, and
floating-point literals with the #def i ne directive.
5. Which happens first: your program is compiled or pre-
processed?
6. What C++ keyword is used to replace the #def i ne prepro-
cessor directive?
7. When do you use the angled brackets in an #i ncl ude, and
when do you use double quotation marks?
8. Which are easier to change: defined literals or literals that
you type throughout a program? Why?
9. Which header file should you include in almost every C++
program you write?
10. True or false: The #def i ne in the following:
#def i ne MESSAGE Pl ease pr ess Ent er t o cont i nue. . .
changes this statement:
cout << MESSAGE;
11. What is the output from the following program?
/ / Fi l ename: C6EXER, C
#i ncl ude <i ost r eam. h>
#def i ne AMT1 a+a+a
#def i ne AMT2 AMT1 - AMT1
mai n( )
{
i nt a=1;
cout << Amount i s << AMT2 << \ n;
r et ur n 0;
}
Chapter 6 o Preprocessor D irectives
130
Even if you get this right, you will appreciate the side effects
of #def i ne. The const keyword (discussed in Chapter 4,
Variables and Literals) before a constant variable has none
of the side effects that #def i ne has.
Review Exerc ises
1. Write a program that prints your name to the screen. Use a
defined literal for the name. Do not use a character array,
and dont type your actual name inside the cout .
2. Suppose your boss wanted you to write a program that
produced an exception report. If the companys sales are
less than $100,000.00 or more than $750,000.00, your boss
wants your program to print the appropriate message. You
learn how to produce these types of reports later in the book,
but for now just write the #def i ne statements that define
these two floating-point literals.
3. Write the cout statements that print your name and birth
date to the screen. Store these statements in their own file.
Write a second program that includes the first file and
prints your name and birth date. Be sure also to include
<iostream.h>, because the included file contains cout
statements.
4. Write a program that defines the ten digits, 0 through 9, as
literals ZERO through NI NE. Add these ten defined digits and
print the result.
Summary
This chapter taught you the #i ncl ude and #def i ne preprocessor
directives. Despite the fact that these directives are not executed,
they temporarily change your source code by merging and defining
literals into your program.
131
EXAMPLE
C+ + By
The next chapter, Simple Input/Output, explains input and
output in more detail. There are ways to control precision when
using ci n and cout , as well as built-in functions that format input
and output.
Chapter 6 o Preprocessor D irectives
132