C/C++ Pre-processor Commands

cppreference.com > C/C++ Pre-processor Commands

#define

Syntax:

  #define macro-name replacement-string

The #define command is used to make substitutions throughout the file in which it is located. In other words, #define causes the compiler to go through the file, replacing every occurrence of macro-name with replacement-string. The replacement string stops at the end of the line.

Here's a typical use for a #define (at least in C):

   #define TRUE 1
   #define FALSE 0
   ...
   int done = 0;
   while( done != TRUE ) {
      ...
   }

Another feature of the #define command is that it can take arguments, making it rather useful as a pseudo-function creator. Consider the following code:

   #define absolute_value( x ) ( ((x) < 0) ? -(x) : (x) )
   ...
   int num = -1;
   while( absolute_value( num ) ) {
      ...
   }

It's generally a good idea to use extra parentheses when using complex macros. Notice that in the above example, the variable "x" is always within it's own set of parentheses. This way, it will be evaluated in whole, before being compared to 0 or multiplied by -1. Also, the entire macro is surrounded by parentheses, to prevent it from being contaminated by other code. If you're not careful, you run the risk of having the compiler misinterpret your code.

Here is an example of how to use the #define command to create a general purpose incrementing for loop that prints out the integers 1 through 20:

 #define count_up( v, low, high ) \
   for( (v) = (low); (v) <= (high); (v)++ )          

 ...            

 int i;
 count_up( i, 1, 20 ) {
   printf( "i is %d\n", i );
 }

#error

Syntax:

  #error message

The #error command simply causes the compiler to stop when it is encountered. When an #error is encountered, the compiler spits out the line number and whatever message is. This command is mostly used for debugging.

#include

Syntax:

  #include <filename>
  #include "filename"

This command slurps in a file and inserts it at the current location. The main difference between the syntax of the two items is that if filename is enclosed in angled brackets, then the compiler searches for it somehow. If it is enclosed in quotes, then the compiler doesn't search very hard for the file.

While the behavior of these two searches is up to the compiler, usually the angled brackets means to search through the standard library directories, while the quotes indicate a search in the current directory. The spiffy new C++ #include commands don't need to map directly to filenames, at least not for the standard libraries. That's why you can get away with

   #include <iostream>

and not have the compiler choke on you.

#line

Syntax:

  #line line_number "filename"

The #line command is simply used to change the value of the __LINE__ and __FILE__ variables. The filename is optional. The __LINE__ and __FILE__ variables represent the current file and which line is being read. The command

   #line 10 "main.cpp"

changes the current line number to 10, and the current file to "main.cpp".

#pragma

The #pragma command gives the programmer the ability to tell the compiler to do certain things. Since the #pragma command is implementation specific, uses vary from compiler to compiler. One option might be to trace program execution.

#if, #ifdef, #ifndef, #else, #elif, #endif

These commands give simple logic control to the compiler. As a file is being compiled, you can use these commands to cause certain lines of code to be included or not included.

   #if expression

If the value of expression is true, then the code that immediately follows the command will be compiled.

   #ifdef macro

If the macro has been defined by a #define statement, then the code immediately following the command will be compiled.

   #ifndef macro

If the macro has not been defined by a #define statement, then the code immediately following the command will be compiled.

A few side notes: The command #elif is simply a horribly truncated way to say "elseif" and works like you think it would. You can also throw in a "defined" or "!defined" after an #if to get added functionality.

Here's an example of all these:

   #ifdef DEBUG
     cout << "This is the test version, i=" << i << endl;
   #else
     cout << "This is the production version!" << endl;
   #endif

You might notice how that second example could make debugging a lot easier than inserting and removing a million "cout"s in your code.

Predefined preprocessor variables

Syntax:

  __LINE__
  __FILE__
  __DATE__
  __TIME__
  __cplusplus
  __STDC__

The following variables can vary by compiler, but generally work:

The __LINE__ and __FILE__ variables represent the current line and current file being processed.
The __DATE__ variable contains the current date, in the form month/day/year. This is the date that the file was compiled, not necessarily the current date.
The __TIME__ variable represents the current time, in the form hour:minute:second. This is the time that the file was compiled, not necessarily the current time.
The __cplusplus variable is only defined when compiling a C++ program. In some older compilers, this is also called c_plusplus.
The __STDC__ variable is defined when compiling a C program, and may also be defined when compiling C++.

#, ##

The # and ## operators are used with the #define macro. Using # causes the first argument after the # to be returned as a string in quotes. Using ## concatenates what's before the ## with what's after it.

For example, the command

   #define to_string( s ) # s

will make the compiler turn this command

   cout << to_string( Hello World! ) << endl;

into

   cout << "Hello World!" << endl;

Here is an example of the ## command:

   #define concatenate( x, y ) x ## y
   ...
   int xy = 10;
   ...

This code will make the compiler turn

   cout << concatenate( x, y ) << endl;

into

   cout << xy << endl;

which will, of course, display '10' to standard output.

#undef

The #undef command undefines a previously defined macro variable, such as a variable defined by a #define.