Click above to get retro games delivered to your door ever month!

   Preprocessor

   The  compiler's  first pass contains an  integral  preprocessor.  This
   supports  all  directives defined in the ANSI  draft.  A  preprocessor
   directive  is  an instruction to the preprocessor to  carry  out  some
   change  on  the C source file. They are normally used to  make  source
   files  simpler  to customize for different execution  environments  by
   carrying  out  token substitution, the insertion of  the  contents  of
   other  source  files and to suppress compilation of  sections  of  the
   source file.

   Preprocessor directives begin with # as the first non-blank  character
   on a line. Spaces and tabs can appear between the # and the directive.
   Some  preprocessor directives may be followed by arguments or  values.
   Any  text  that  follows a directive must be a valid C  or  C++  style
   comment.  Preprocessor directives may appear anywhere within a  source
   file,  but they are current only from the point of definition  through
   to  the  end  of  the file in  which  they  appear.  Two  preprocessor
   operators  are  supported by the compiler, they  are  the  stringizing
   operator # and the concatenation operator ##. These will be  discussed
   shortly. Supported preprocessor directives are:

   #if,  #else, #endif, #elif, #ifdef, #ifndef, #error,  #line,  #define,
   #undef, #include, #pragma

   Manifest Constants
   The directive #define followed by an identifier and a value is  used
   to give meaningful names to constant values. Such values are known  as
   manifest constants, e.g.

   #define MAX 1024
   The  preferred method of defining manifest constants in C++ is to  use
   the const type specifier:

   const int MAX = 1024;
   The  #define directive is also used to give meaningful identifiers  to
   keywords  and commonly used statements or expressions. In  the  latter
   case  the  products  are either  parameterized  or  non  parameterized
   macros. These are discussed in the following section.

   After  an  identifier has been defined, it cannot be  redefined  to  a
   different value without removing the original definition. This is done
   by  the  use  of  the directive #undef, which  when  followed  by  the
   identifier  causes  the  preceding #define with the same  name  to  be
   forgotten  by  the  preprocessor.  If it  is  not  used,  any  further
   definitions  with  the  same name must be identical  to  the  original
   definition.

   Macros
   C++ supports full macro capabilities, although the preferred method is
   to use the inline type specifier where possible since this  guarantees
   the  correct  evaluation  of passed parameters and  return  types.  An
   example macro would be:

   #define min(a, b) (((a) < (b)) ? (a) : (b))
   where  the  extra  parentheses are required to  ensure  that  compound
   arguments  passed to the macro are evaluated correctly. The  preferred
   method of implementing this function in C++ would be:

   inline int min(int a, int b) { return ((a < b) ? a : b); }
   The  preprocessor operator # is known as the stringizing operator.  It
   is only used with macros that take arguments. This operator, when used
   to precede a formal parameter name in the body of a macro  definition,
   causes  the  corresponding actual argument, passed when the  macro  is
   invoked,  to  be enclosed in quotation  marks  (stringized).  Normally
   argument substitution does not take place inside strings. For example,
   if the preprocessor encounters the following definition :

   #define X(y) printf("y = %d\n", y)
   then the following :
   X(abc);
   will expand to :
   printf("y = %d\n", abc) ;

   Note  that  the  y in the string was not replaced.  If  the  macro  is
   written using the stringizing operator :

   #define X(y) printf(#y " =%d\n",y);
   it will expand to :

   printf("abc" " =%d\n",abc);

   The adjacent strings will be concatenated. Note that when  stringizing
   white  space  preceding  the first token of the  actual  argument  and
   following  the  last  token is ignored. In addition  any  white  space
   between the tokens in the actual argument is reduced to a single white
   space   in  the  resulting  string  and  any  adjacent   strings   are
   automatically  concatenated provided they are separated only by  white
   space.  If  a character contained within the argument  would  normally
   require an escape sequence, the required backslash \ is  automatically
   inserted before the character.

   The concatenation_operator ## allows separate tokens to be joined  _
   into  a single token. It cannot be the first or last token in a  macro
   definition.

   If a formal parameter in the definition of a macro is preceded by  the
   concatenation  operator, the formal parameter is immediately  replaced
   by the unexpanded actual argument. No macro expansion is performed  on
   the  argument prior to its replacement. Next, each occurrence  of  the
   concatenation  operator  is  removed, and  the  tokens  preceding  and
   following  it are joined together into a single token.  Providing  the
   result is a valid token it is re-checked to see whether it is itself a
   valid macro name, and if it is substitution is carried out as  normal.
   Extensive  use  is made of this operator within the  C++  header  file
   generic.hpp.

   Finally  it should be noted that circular macro definitions expand  as
   follows:

   #define unix unix
   will expand to unix.