Lecture Notes for Advanced Programming II

22 January 2004 - Include files

Outline

• Textual Inclusion

• Include Filename Syntax

• The std Namespace

• The C++ Standard Include Files

• C Standard Include Files

• Example Standard C Include Files

• Other Include Files

Include Files

• Part of standard C and C++.

  • Part of the standard preprocessor.

  • "Preprocessor" means "precompilation".

  • The g++ and CC -E option runs your code through the preprocessor and nothing else.

• Include statement syntax is not C++ syntax.

  #include "include-file-name"

  #include <include-file-name>

• < > and "" have different search paths.

  • < > usually searches only the system directories.

  • " " searches other directories first, then system directories.

    • For example, " " searches . (the current directory).

    • This depends on the compiler.

The -I Option

• The -I compiler command-line option manipulates the "..." search paths.

  • Does not effect the <...> search paths.

  • Available for g++ and CC.

• For example: g++ -Imylib ...

  • Search ./mylib, then ., then ...

• -I options are cumulative.

  • g++ -Iliba -Ilibb ... searches liba, then libb then ...

• Some compilers support options to influence the < > search path too.

  • The g++ support for this is too ugly to talk about.

Textual Inclusion

• Includes implement textual inclusion.

  • The include-file contents replaces the include statement.

  • This causes code and variable duplication, not sharing.

  • Not like packages in Ada or Java.

• Textual inclusion can cause problems.

  • Large source files, circular includes, and duplicate code.

• Learn and use the #ifndef idiom for include files.

  #ifndef _includefile_h_
  #define _includefile_h_
  
  // Included material here.
  
  #endif
  

  • Stops duplicate or circular includes.

Include File Duplication

• Declaring non-static, non-extern variables in include files is (usually) a mistake.

  * cat a.cc #include "i.h" void a() { } * cat b.cc #include "i.h" int main() { } * cat i.h #ifndef _i_h_defined_ #define _i_h_defined_ int i; #endif * g++ -c a.cc * g++ -c b.cc * g++ a.o b.o b.o: multiple definition of i a.o: first defined here ld returned 1 exit status *

Include Filename Syntax

• Standard include files need standard names.

  • Many pre-standard extensions; .h, .hh, .H, .hxx

• The standard eliminated the extension.

  • C++ and C standard include files have no extensions - no .h

  • Some compilers may still accept .h standard includes.

    • Don't use it; it's nonstandard.

• It usually doesn't mater, but sometimes it does.

  • <string> is not <string.h> is not <cstring>

• Other include filenames can be arbitrary.

  • Filenames can include local conventions; / vs. \.

  • Watch out for portability.

The std Namespace

• The C++ and C standard includes define names inside the std namespace.

  • Names should be prefixed with std::.

  • using declarations make this less cumbersome.

  • However, std:: is useful documentation.

    • Now where did that come from?

• Compilers respect this to varying degrees.

  • Don't rely on a compiler's particular treatment.

  • Use std:: or explicitly eliminate it.

• Namespaces prevent conflicts between old and new names.

  • The old names are in the global name space.

  • The new names are in the std name space.

  • Both max() and std::max() can live in harmony.

Namespaces vs. Include Files

• Avoid subverting namespaces in include files.

  • It may cause unintentional name clashes in the including file's code.

  • Include files should be good guests.

  • Be especially careful of using namespace x.

  Bad:	Good:
  #ifndef _t_h_defined_ #define _t_h_defined_ #include <vector> namespace std; class board { vector<int> b; // and so on }; #endif	#ifndef _t_h_defined_ #define _t_h_defined_ #include <vector> class board { std::vector<int> b; // and so on }; #endif

The C++ Standard Include Files

• There are somewhere around 50 standard include files.

• Stream IO include files.

  • <iostream>, <iomanip>, <fstream>

• STL include files.

  • <vector>, <list>, <map>, <iterator>, <algorithm>, <utility>, <queue>, <stack>, <deque>, <set>, <bitset>, <functional>, <memory>

• Exception include files.

  • <exception>, <stdexcept>

• String include files.

  • <string>, <sstream>

  • But not <strstream> (it's deprecated).

• Odds and ends.

  • <locale>, <limits>, <typeinfo>

C Standard Include Files

• C defines a set of standard include files too.

  • These are available for use in C++.

  • From C++, they are part of the std namespace, sometimes.

    • It depends on the compiler.

    • Macros are not part of a namespace.

• Access them using C++ include conventions.

  • Drop the .h and prepend a 'c'.

  • For example, given the C include assert.h, use

    #include <cassert>
    

  • Accessing the .h forms from C++ is nonstandard.

  • c-prepended headers make the proper C++ extern declarations, .h headers do not.

Example Standard C Include Files

• Assert macros in <cassert>.

  assert((0 <= i) and (i < N));
  

  assert()'s a macro, no std::.

• Character functions in <cctype>.

  ch = std::toupper(ch);
  

• Math functions in <cmath>.

  double x = std::log(M_PI);
  

  M_PI is a macro, log() is a function; std::M_PI doesn't compile.

• System-dependent limits in <climits>.

  cout << "Biggest int is " << INT_MAX << "\n"
  

  std::INT_MAX doesn't compile either.

• Time utilities in <ctime>.

Other Include Files

• Any other include files are non-standard.

  • strcasecmp(), strings.h, X Window System includes.

  • Filename syntax is arbitrary.

  • These are non-standard, potentially non-portable features.

• "non-standard" is not bad - "unconventional" is bad

  • Gratuitously non-standard is bad too.

• Don't #include source (.cc) files, but the STL does.

  • Usually considered a hostile act.

  • Templates are excused from this convention.

Points to Remember

• Include statements implement textual inclusion.

  • Big code, infinite includes, duplicate entities.

• Become familiar with the standard C and C++ include files.

  • Reduce your work, improve code (and your) portability.

• C++ standard includes have no extensions.

  • C standard includes in C++ have a c prefix too.

  • Non-standard includes have whatever.

• Learn and follow the include conventions.

  • Don't include source, don't subvert namespaces.

  • Learn the local conventions too.

This page last modified on 22 January 2004.