C++ Tutorials - Using the Preprocessor

Using the C/C++ Preprocessor

Basic Reference

Preprocessor Overview

Independent of the C/C++ language
Essentially a textual replacement facility
Actual program is cpp, but is usually invisibly invoked by the g++/gcc compiler scripts.
Generates an intermediate textual string consisting of the source file trasnformed by the preprocessor commands (directives).
Basic facilities:
- Inclusion of header files
  - Uses #include directive
  - Essentially a copy/paste of the file into the source file at the point of the inclusion
- Macros
  - code assigned a name
  - when the name is encountered in the source, it is replaced with the corresponding code.
  - can be parameterized
  - introduced via the #define directive
  - since ignorant of C/C++ (and rules of precedence), can be treacherous if not used properly
```
#define PI 3.1415
#define MAX(x, y) x > y ? x : y
#define TWICE(x) x * 2				// should be (x) * 2 … try it out on TWICE(3+1)
						
```
- Conditional compilation
  - Allows testing of preprocessor variables (macros) — if result is true, the relevant code is passed through to the compiler
  - uses the directives (among others): #if, #ifdef, #ifndef, #else, #endif,
```
//#define OSX
#define WIN32
…
…
…
#ifdef WIN32	// Windows 32-specific code
	…
#else		// otherwise (OSX)
	…
#endif
				
```

Interface vs Implementation

.h file provides (for the most part) the interface
- Portion visible to the public
- Information that would be exported to an API
.cpp file comprises the implementation
- how the interface is realized
- of no concern to the user (other than its efficiency)

Why `file.cpp` has a `#include` of its own `.h` File

Keeps the .h and .cpp files in sync
- Function declaration and definition header discrepancies are easily caught
Provides headers at the top of the file thus allowing the functions to appear in any order without worrying about forward references.

Who Sees What and Why?

Suppose we have

main.cpp
array.h
array.cpp

In order to::

compile array.cpp (compiler_array.cpp)
- need to include array.h
- compiler_array.cpp needs the array declaration
  - Need the name (Array) for scope resolution (Array::)
  - Need the function declarations in order to implement them
  - Need the data members in order to work with them
- compiler_array.cpp does not need main.cpp
- compile main.cpp (compiler_main.cpp)
  - need to include array.h
  - compiler_main.cpp needs
    - to know the size of the Array object, when main.cpp contains an Array declaration
    - to know the functions of Array when main.cpp calls an Array function
  - compiler_main.cpp does not need to know about array.cpp
    - We can thus develop our main even before we have fully implemented our class!
- link the program
  - need main.o and array.o

Include Files

#include is used to bring in declarations from other modules — typically class, function, type, and global variable declarations

.h files, as well as .cpp files need to see such information.

// file person.h

#include "name.h"	// see declaration of name below

class person {
public:
	…
private:
	Name name;	// compiler needs to see declaration of Name class — in name.h
	…
};

originally, only .c files did the #include
- the programmer would have to determine all the header files required
  - this became a transitive operation; i.e., many of the header files needed declarations from other header files
  - in addition, the order was important — if a declaration in a header file required a declaration from another header file, the latter had to precede the former in the list of #include's
eventually programmers began having each file (.h's as well as .c's) include whatever headers it required
- i.e., each file was responsible for its own (and ONLY its own) included headers
however, this led to a problem …

Adding a #Include Guard (Macro Guard)

Wiki Reference

The Problem — Preventing multiple inclusions of the same `.h` file

The following code is illegal — it causes a duplicate declaration compilation error:

class C {
...
};
...
class C {
...
};

This presents the following problem:

Suppose we are writing an application involving students and transcripts
- each student is represented as an object of a Student class
- within the Student object is a list of courses
  - rather than using a low-level primitive array, we use an object of a more sophisticated, select-sizing Vector class
    - this requires an inclusion of the Vector class' header file, vector.h
```
// file student.h
...
#include "vector.h"  // for the vector of courses below
...

class Student {
	…
private:
	…
	Vector courses(100);
};
								
```
- The main source file references Student objects and thus has a#include "student.h"
- The main source file, however, also has a need for its own vector (of Student objects) and thus has its own #include vector.h
```
// file main.cpp
...
#include "student.h"		// We're a Student application
#include "vector.h"		//  For the vector of students below
...

Vector students(1000);		
...
				
```

The above code suffers from the same duplicate class definition problem as above.

The Solution: Include Guards

To prevent this, we prevent the same .h file from being included more than once

Introduce a preprocessor variable name deriving from the .h file name
- By convention, its the file name in caps followed by _H
  - As a general convention, preprocessor variables are all upper case
Use the preprocessor's conditional compilation facility to check whether the file has already been included and skip it if it has
```
#ifndef VECTOR_H			// if VECTOR_H has not already been defined
#define VECTOR_H			// define it
	...
#endif 
			
```
First time encountered the VECTOR_H variable has not been seen (and thus not defined), so the code is pasted in
Successive encounters evaluate the condition to false (the variable IS defined) and thus skip the code

Other uses of conditional compilation

Platform-dependent code
Development/production phase code