Separate Compilation and Namespaces in C++

This chapter is from the book

Absolute C++

Learn More Buy

This chapter is from the book

This chapter is from the book 

Absolute C++

Learn More Buy

Namespaces

What's in a name? That which we call a rose. By any other name would smell as sweet.
—William Shakespeare, Romeo and Juliet

When a program uses different classes and functions written by different programmers, there is a possibility that two programmers will use the same name for two different things. Namespaces are a way to deal with this problem. A namespace is a collection of name definitions, such as class definitions and variable declarations. A namespace can, in a sense, be turned on and off so that when some of its names would otherwise conflict with names in another namespace, it can be turned off.

Namespaces and Using Directives

We have already been using the namespace that is named std. The std namespace contains all the names defined in many of the standard C++ library files (such as iostream). For example, when you place the following at the start of a file

#include <iostream>

that places all the name definitions (for names like cin and cout) into the std namespace. Your program does not know about names in the std namespace unless you specify that it is using the std namespace. To make all the definitions in the std namespace available to your code, you insert the following using directive:

using namespace std;

A good way to see why you might want to include this using directive is to think about why you might want to not include it. If you do not include this using directive for the namespace std, then you can define cin and cout to have some meaning other than their standard meaning. (Perhaps you want to redefine cin and cout because you want them to behave a bit differently from the standard versions.) Their standard meaning is in the std namespace, and without the using directive (or something like it), your code knows nothing about the std namespace, and so, as far as your code is concerned, the only definitions of cin and cout are whatever definition you give them.

Every bit of code you write is in some namespace. If you do not place the code in some specific namespace, then the code is in a namespace known as the global namespace. So far, we have not placed any code we wrote in any namespace and so all our code has been in the global namespace. The global namespace does not have a using directive because you are always using the global namespace. You could say there is always an implicit automatic using directive that says you are using the global namespace.

Note that you can be using more than one namespace at the same time. For example, we are always using the global namespace and we are usually using the std namespace. What happens if a name is defined in two namespaces and you are using both namespaces? This results in an error (either a compiler error or a run time error, depending on the exact details). You can have the same name defined in two different namespaces, but if that is true, then you can only use one of those namespaces at a time. However, this does not mean you cannot use the two namespace in the same program. You can use them each at different times in the same program.

For example, suppose NS1 and NS2 are two namespaces and suppose myFunction is a void function with no arguments that is defined in both namespaces but defined in different ways in the two namespaces, then the following is legal:

{
  using namespace NS1;
  myFunction( );
}
{
  using namespace NS2;
  myFunction( );
}

The first invocation would use the definition of myFunction given in the namespace NS1, and the second invocation would use the definition of the myFunction given in the namespace NS2.

Recall that a block is a list of statements, declarations, and possible other code, enclosed in braces {}. A using directive at the start of a block applies only to that block. So the first using directive applies only in the first block and the second using directive applies only in the second block. The usual way of phrasing this is to say that the scope of the NS1 using directive is the first block, while the scope of the NS2 using directive is the second block. Note that because of this scope rule, we are able to used two conflicting namespaces in the same program (such as in a program that contains the two blocks we discussed in the previous paragraph).

Normally, you place a using directive at the start of a block, but if you place further down in the block, you need to know the precise scope of a using directive. The scope of a using directive is from the place where it occurs to the end of the block. You may have a using directive for the same namespace in more than one block, so the entire scope of a namespace may cover multiple disconnected blocks. When you use a using directive in a block, it is typically the block consisting of the body of a function definition.

If you place a using directive at the start of a file (as we have usually done so far), then the using directive applies to the entire file. A using directive should normally be placed near the start of a file (or the start of a block), but the precise scope rule is that the scope of a using directive that is outside of all blocks is from the occurrence of the using directive to the end of the file.

Creating a Namespace

In order to place some code in a namespace, you simply place it in a namespace grouping of the following form:

namespace Name_Space_Name
{
  Some_Code
}

When you include one of these groupings in your code, you are said to place the names defined in Some_Code into the namespace Name_Space_Name. These names (really the definitions of these names) can be made available with the using directive:

using namespace Name_Space_Name;

For example, the following, taken from Display 5, places a function declaration in the namespace Space1:

namespace Space1
{
  void greeting( );
}

If you look again at Display 5, you see that the definition of the function greeting is also placed in namespace Space1. That is done with the following additional namespace grouping:

namespace Space1
{
  void greeting( )
  {
    cout << "Hello from namespace Space1.\n";
  }
}

Note that you can have any number of these namespace groupings for a single namespace. In Display 5, we used two namespace groupings for namespace.

Display 5—Namespace Demonstration

#include <iostream>
using namespace std;

namespace Space1
{
  void greeting( );
}

namespace Space2
{
  void greeting( );
}

void bigGreeting( );

int main( )
{
  {//This block use definitions in namespaces Space2, std, and the global namespace
    using namespace Space2;
    greeting( );
  }

  {//This block use definitions in namespaces Space1, std, and the global namespace
    using namespace Space1;
    greeting( );
  }

//Names out here only use definitions in namespaces std, and the global namespace
  bigGreeting( );

  return 0;
}

namespace Space1
{
  void greeting( )
  {
    cout << "Hello from namespace Space1.\n";
  }
}

namespace Space2
{
  void greeting( )
  {
    cout << "Greetings from namespace Space2.\n";
  }
}

void bigGreeting( )
{
  cout << "A Big Global Hello!\n";
}

Sample Screen Dialogue

Greetings from namespace Space2.
Hello from namespace Space1.
A Big Global Hello!

Every name defined in a namespace is available inside the namespace groupings, but the names can also be made available to code outside of the namespace. For example, the function declaration and function definition in the namespace Space1 can be made available with the using directive

using namespace Space1

as illustrated in Display 5.

Using Declarations

This section describes a way to qualify a single name so you can make only one name from a namespace available to your program, rather than making all the names in a namespace available.

Suppose you are faced with the following situation. You have two namespaces: NS1 and NS2. You want to use the function fun1 defined in NS1 and the function fun2 defined in namespace NS2. The complication is that both NS1 and NS2 define a function myFunction. (Assume all functions in this discussion take no arguments so overloading does not apply). You cannot use

using namespace NS1;
using namespace NS2;

This would potentially provide confliction definitions for myFunction. (If the name myFunction is never used, then most compilers will not detect the problem and will allow your program to compile and run.)

What you need is a way to say you are using fun1 in namespace NS1 , fun2 in namespace NS2, and nothing else in the namespaces NS1 and NS2. The following is your solution:

using NS1::fun1;
using NS2::fun2;

A qualification of the form

using Name_Space::One_Name;

makes the (definition of the) name One_Name from the namespace Name_Space available, but does not make any other names in Name_Space available. This is called a using declaration.

Note that the scope resolution operator :: that we use in these using declarations is the same as the scope resolution operator we use when defining member functions, and these two uses of the scope resolution operator have a similarity. For example, in Display 2, we had the following function definition:

void DigitalTime::advance(int hoursAdded, int minutesAdded)
{
  hour = (hour + hoursAdded)%24;
  advance(minutesAdded);
}

In this case, the :: means that we are defining the function advance for the class DigitalTime, as opposed to any other function named advance in any other class. Similarly,

using NS1::fun1;

means we are using the function named fun1 as defined in the namespace NS1, as opposed to any other definition of fun1 in any other namespace.

There are two differences between a using declaration, such as

using std::cout;

and a using directive such as

using namespace std;

The differences are

1. A using declaration makes only one name in the namespace available to your code, while a using directive makes all the names in a namespace available.

2. A using declaration introduces a name (like cout) into your code so no other use of the name can be made. However a using directive only potentially introduces the names in the namespace.

Point 1 is pretty obvious. Point 2 has some subtleties. For example, suppose the namespaces NS1 and NS2 both provide definitions for myFunction, but have no other name conflicts, then the following will produce no problems:

using namespace NS1;
using namespace NS2;

provided that (within the scope of these directives) the conflicting name myFunction is never used in your code.

On the other hand, the following is illegal, even if the function myFunction is never used:

using NS1::myFunction;
using NS2::myFunction;

Sometimes this subtle point can be important, but it does not impinge on most routine code. So, we will often use the term using directive loosely to mean either a using directive or a using declaration.

Qualifying Names

This section introduces a way to qualify names that we have not discussed before. Suppose that you intend to use the name fun1 as defined in the namespace NS1, but you only intend to use it one time (or a small number of times). You can name the function (or other item) using the name of the namespace and the scope resolution operator as follows:

NS1::fun1( );

This form is often used when specifying a parameter type. For example, consider

int getInput(std::istream inputStream)
. . .

In the function getInput, the parameter inputStream is of type istream where istream is defined as in the std namespace. If this use of the type name istream is the only name you need from the std namespace (or if all the names you need are similarly qualified with std::), then you do not need

using namespace std;

nor

using std::istream;

Note that you can use std::istream even within the scope of a using directive for another namespace that also defines the name istream. In this case, std::istream and istream will have different definitions. For example, consider.

using namespace MySpace;
void someFunction(istream p1, std::istream p2);

Assuming istream is a type defined in the namespace MySpace, then p1 will have the type istream as defined in MySpace, and p2 will have the type istream as defined in the std namespace.

Programming Example: A Class Definition in a Namespace

In Displays 6 and 7, we have again rewritten both the header file dtime.h for the DTimeSavitch. Note that the namespace DTimeSavitch spans the two files dtime.h and dtime.cpp. A namespace can span multiple files.

Display 6—Placing a Class in a Namespace (Header File)

//This is the header file dtime.h.
//A better version of this class definition will be given in Displays 8 and 9.
#ifndef DTIME_H
#define DTIME_H

#include <iostream>
using std::istream;
using std::ostream;

namespace DTimeSavitch
{
  class DigitalTime
  {
   <The definition of the class DigitalTime is the same as in Display 1.>
  };
}// DTimeSavitch

#endif //DTIME_H

Display 7—Placing a Class in a Namespace (Implementation File)

//This is the implementation file: dtime.cpp 
#include <iostream>
#include <cctype>
#include <cstdlib>
using std::istream;
using std::ostream;
using std::cout;
using std::cin;
#include "dtime.h"

namespace DTimeSavitch
{
  <All the function definitions from Display 2 go here.>
}// DTimeSavitch

If you rewrite the definition of the class DigitalTime, as shown in Displays 6 and 7, then the application program in Display 3 needs to specify the namespace DTimeSavitch in some way, such as the following:

using namespace DTimeSavitch;

or

using DTimeSavitch::DigitalTime;

Programming Tip: Choosing a Name for a Namespace

It is a good idea to include your last name or some other unique string in the names of your namespaces, so as to reduce the chance that somebody else will use the same namespace name as you do. With multiple programmers writing code for the same project it is important that namespaces that are meant to be distinct really do have distinct names. Otherwise, you can easily have multiple definitions of the same names in the same scope. That is why we included the name Savitch in the namespace DtimeSavitch in Display 6.

Unnamed Namespaces

A compilation unit is a file, such as a class implementation file, along with all the files that are #included in the file, such as the interface header file for the class. Every compilation unit has an unnamed namespace. A namespace grouping for the unnamed namespace is written in the same way as any other namespace, but no name is given, as in the following example:

namespace
{
  void sampleFunction( )
    .
    .
    .
} //unnamed namespace 

All the names defined in the unnamed namespace are local to the compilation unit, and so the names can be reused for something else outside the compilation unit. For example, Display 8 shows a rewritten (and our final) version.

Display 8—Hiding the Helping Functions in a Namespace—Interface File

//This is the header file dtime.h. This is the interface for the class DigitalTime.
//Values of this type are times of day. The values are input and output in 24 hour
//notation as in 9:30 for 9:30 AM and 14:45 for 2:45 PM.
#ifndef DTIME_H
#define DTIME_H

#include <iostream>
using std::istream;
using std::ostream;

namespace DTimeSavitch
{
  class DigitalTime
  {
  public:
    DigitalTime(int theHour, int theMinute);

    DigitalTime( );
    //Initializes the time value to 0:00 (which is midnight).

    getHour( ) const;
    getMinute( ) const;

    void advance(int minutesAdded);
    //Changes the time to minutesAdded minutes later.

    void advance(int hoursAdded, int minutesAdded);
    //Changes the time to hoursAdded hours plus minutesAdded minutes later.

    friend bool operator ==(const DigitalTime& time1, 
                const DigitalTime& time2);
    friend istream& operator >>(istream& ins, DigitalTime& theObject);
    friend ostream& operator <<(ostream& outs, 
                  const DigitalTime& theObject);
  private:
    int hour;
    int minute;
  };

} //DTimeSavitch
#endif //DTIME_H

The helping functions digitToInt, readHour, and readMinute are used outside the unnamed namespace without any namespace qualifier. Any name defined in the unnamed namespace can be used without qualification anywhere in the compilation unit. (Of course, this needed to be so, since the unnamed namespace has no name to use for qualifying its names.)

It is interesting to note how unnamed namespaces interact with the C++ rule that you cannot have two definitions of a name (in the same namespace). There is one unnamed namespace in each compilation unit. It is easily possible for compilation units to overlap. For example, both the implementation file for a class and an application program using the class would normally both include the header file (interface file) for the class. Thus, the header file is in two compilation units and hence participates in two unnamed namespaces. As dangerous as this sounds, it will normally produce no problems as long as each compilation unit's namespace makes sense when considered by itself. For example, if a name is defined in the unnamed namespace in the header file, it cannot be defined again in the unnamed namespace in either the implementation file or the application file. So, a name conflict is avoided.

namespace
{

Both names in the global namespace and names in the unnamed namespace may be accessed without qualifier. However, names in the global namespace have global scope (all the program files), while names in an unnamed namespace are local to a compilation unit.

This confusion between the global namespace and the unnamed namespace does not arise very much in writing code, since there is a tendency to think of names in the global namespace as being "in no namespace," even though that is not technically correct. However, the confusion can easily arise when discussing code.