Namespaces

What’s the Problem?

Imagine that you’re working with two libraries provided by different organizations. Those two organizations don’t know anything about each other (or at least, are not making any assumptions), and they don’t know anything about your code, either.

Each of those libraries contain a function with the same name – a name conflict. How can you work with those libraries and still call either of the specified functions? This is where namespaces come in, in C++. If you’re familiar with Java, you’ll know about Java packages, which solve the same problem for that language.

Example

Imagine that you’re supporting an application that needs to return information about a country:

//
//  Countries.hpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#ifndef Countries_hpp
#define Countries_hpp

#include <string>

const std::string& getCountry();
const std::string& getCapitalCity();
const std::string& getCurrencySymbol();

#endif /* Countries_hpp */
//
//  Countries.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include "Countries.hpp"

const std::string& getCountry()
{
  static const std::string& country = "England";
  return country;
}
const std::string& getCapitalCity()
{
  static const std::string capital = "London";
  return capital;
}

const std::string& getCurrencySymbol()
{
  static const std::string symbol = "£";
  return symbol;
}

Here’s a main program that uses the Countries code:

//
//  main.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include <iostream>
#include "Countries.hpp"

int main(int argc, const char * argv[]) 
{
  std::cout << "The capital of "
            << getCountry() << " is "
            << getCapitalCity() << std::endl;
  std::cout << "Its currency is "
            << getCurrencySymbol() << std::endl;
  
  return 0;
}

It outputs the following:

The capital of England is London
Its currency is £
Program ended with exit code: 0

Now, what if you wanted to have the same functionality, but you’re obtaining your code from different countries, say, England and France?

Let’s use namespaces to do this:

//
//  England.hpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#ifndef England_hpp
#define England_hpp

#include <string>

namespace England
{
  const std::string& getCountry();
  const std::string& getCapitalCity();
  const std::string& getCurrencySymbol();
}

#endif /* England_hpp */
//
//  England.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include "England.hpp"

namespace England
{
  const std::string& getCountry()
  {
    static const std::string& country = "England";
    return country;
  }
  const std::string& getCapitalCity()
  {
    static const std::string capital = "London";
    return capital;
  }

  const std::string& getCurrencySymbol()
  {
    static const std::string symbol = "£";
    return symbol;
  }
}
//
//  France.hpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#ifndef France_hpp
#define France_hpp

#include <string>

namespace France
{
  const std::string& getCountry();
  const std::string& getCapitalCity();
  const std::string& getCurrencySymbol();
}

#endif /* France_hpp */
//
//  France.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include "France.hpp"

namespace France
{
  const std::string& getCountry()
  {
    static const std::string& country = "France";
    return country;
  }
  const std::string& getCapitalCity()
  {
    static const std::string capital = "Paris";
    return capital;
  }

  const std::string& getCurrencySymbol()
  {
    static const std::string symbol = "€";
    return symbol;
  }
}

Here’s a main program that uses the above code:

//
//  main.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include <iostream>
#include "England.hpp"
#include "France.hpp"

int main(int argc, const char * argv[])
{
  {
    using namespace England;
    
    std::cout << "The capital of "
              << getCountry() << " is "
              << getCapitalCity() << std::endl;
    std::cout << "Its currency is "
              << getCurrencySymbol() << std::endl;
  }

  {
    using namespace France;
    
    std::cout << "The capital of "
              << getCountry() << " is "
              << getCapitalCity() << std::endl;
    std::cout << "Its currency is "
              << getCurrencySymbol() << std::endl;
  }

  return 0;
}

It outputs the following:

The capital of England is London
Its currency is £
The capital of France is Paris
Its currency is €
Program ended with exit code: 0

Defining a Namespace

You define a namespace using the following syntax:

namespace namespace_name 
{
  // code declarations
  // methods/functions
  // classes
} // Note: no semicolon

(See examples in the code above.)

Specifying the Use of a Namespace

You can specify that you are referring to an entity defined within a namespace by prefixing that entity name as follows:

namespace_name::entity_name

For example, in the above code, std::cout and std::string indicate that cout and string are defined in the std namespace used in the C++ Standard Library (see later for more details).

Using Directive

It is usually more convenient to use a using directive to specify that a whole scope of code is subject to the use of a namespace:

using namespace namespace_name;

(See examples in the code above.)

Names introduced in a using directive obey normal scope rules. The name is visible from the point of the using directive to the end of the scope in which the directive is found. Entities with the same name defined in an outer scope are hidden.

Having Multiple Namespaces in Scope Simultaneously

It is possible — probably a common occurrence — to have more than one namespace currently in scope.

Let’s change the above code to show how that can be done. I’ve removed all the explicit std:: prefixes from the above code, and instead use suitably located using namespace declarations:

//
//  England.hpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#ifndef England_hpp
#define England_hpp

#include <string>

using namespace std;

namespace England
{
  const string& getCountry();
  const string& getCapitalCity();
  const string& getCurrencySymbol();
}

#endif /* England_hpp */
//
//  England.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include "England.hpp"

using namespace std;

namespace England
{
  const string& getCountry()
  {
    static const string& country = "England";
    return country;
  }
  const string& getCapitalCity()
  {
    static const string capital = "London";
    return capital;
  }

  const string& getCurrencySymbol()
  {
    static const string symbol = "£";
    return symbol;
  }
}
//
//  France.hpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#ifndef France_hpp
#define France_hpp

#include <string>

using namespace std;

namespace France
{
  const string& getCountry();
  const string& getCapitalCity();
  const string& getCurrencySymbol();
}

#endif /* France_hpp */
//
//  France.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include "France.hpp"

using namespace std;

namespace France
{
  const string& getCountry()
  {
    static const string& country = "France";
    return country;
  }
  const string& getCapitalCity()
  {
    static const string capital = "Paris";
    return capital;
  }

  const string& getCurrencySymbol()
  {
    static const string symbol = "€";
    return symbol;
  }
}

Here’s the modified main program that uses the above code:

//
//  main.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include <iostream>

using namespace std;

#include "England.hpp"
#include "France.hpp"

int main(int argc, const char * argv[])
{
  {
    using namespace England;
    
    cout << "The capital of "
              << getCountry() << " is "
              << getCapitalCity() << std::endl;
    cout << "Its currency is "
              << getCurrencySymbol() << std::endl;
  }

  {
    using namespace France;
    
    cout << "The capital of "
         << getCountry() << " is "
         << getCapitalCity() << std::endl;
    cout << "Its currency is "
         << getCurrencySymbol() << std::endl;
  }

  return 0;
}

Its output is the same as before:

The capital of England is London
Its currency is £
The capital of France is Paris
Its currency is €
Program ended with exit code: 0

Nested Namespaces

Namespaces may be nested:

//
//  UK.hpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#ifndef UK_hpp
#define UK_hpp

#include <string>

using namespace std;

namespace UK
{
  namespace England
  {
  const string& getCountry();
  const string& getCapitalCity();
  const string& getCurrencySymbol();
  }

  namespace Scotland
  {
  const string& getCountry();
  const string& getCapitalCity();
  const string& getCurrencySymbol();
  }

  namespace Wales
  {
  const string& getCountry();
  const string& getCapitalCity();
  const string& getCurrencySymbol();
  }

  namespace NorthernIreland
  {
  const string& getCountry();
  const string& getCapitalCity();
  const string& getCurrencySymbol();
  }
}

#endif /* UK_hpp */
//
//  UK.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include "UK.hpp"

using namespace std;

namespace UK
{
  namespace England
  {
    const string& getCountry()
    {
      static const string& country = "England";
      return country;
    }
    const string& getCapitalCity()
    {
      static const string capital = "London";
      return capital;
    }

    const string& getCurrencySymbol()
    {
      static const string symbol = "£";
      return symbol;
    }
  }

  namespace Scotland
  {
    const string& getCountry()
    {
      static const string& country = "Scotland";
      return country;
    }
    const string& getCapitalCity()
    {
      static const string capital = "Edinburgh";
      return capital;
    }

    const string& getCurrencySymbol()
    {
      static const string symbol = "£";
      return symbol;
    }
  }

  namespace Wales
  {
    const string& getCountry()
    {
      static const string& country = "Wales";
      return country;
    }
    const string& getCapitalCity()
    {
      static const string capital = "Cardiff";
      return capital;
    }

    const string& getCurrencySymbol()
    {
      static const string symbol = "£";
      return symbol;
    }
  }

  namespace NorthernIreland
  {
    const string& getCountry()
    {
      static const string& country = "Northern Ireland";
      return country;
    }
    const string& getCapitalCity()
    {
      static const string capital = "Belfast";
      return capital;
    }
    
    const string& getCurrencySymbol()
    {
      static const string symbol = "£";
      return symbol;
    }
  }
}

And here’s a main program that uses the above code:

//
//  main.cpp
//  Namespaces
//
//  Created by Bryan Higgs on 2/7/25.
//

#include <iostream>

using namespace std;

#include "UK.hpp"

int main(int argc, const char * argv[])
{
  using namespace UK;
  {
    {
      using namespace England;
      
      cout << "The capital of "
           << getCountry() << " is "
           << getCapitalCity() << std::endl;
      cout << "Its currency is "
           << getCurrencySymbol() << std::endl;
    }
    
    {
      using namespace Scotland;
      
      cout << "The capital of "
           << getCountry() << " is "
           << getCapitalCity() << std::endl;
      cout << "Its currency is "
           << getCurrencySymbol() << std::endl;
    }
    
    {
      using namespace Wales;
      
      cout << "The capital of "
           << getCountry() << " is "
           << getCapitalCity() << std::endl;
      cout << "Its currency is "
           << getCurrencySymbol() << std::endl;
    }
    
    {
      using namespace NorthernIreland;
      
      cout << "The capital of "
           << getCountry() << " is "
           << getCapitalCity() << std::endl;
      cout << "Its currency is "
           << getCurrencySymbol() << std::endl;
    }
  }

  return 0;
}

It outputs the following:

The capital of England is London
Its currency is £
The capital of Scotland is Edinburgh
Its currency is £
The capital of Wales is Cardiff
Its currency is £
The capital of Northern Ireland is Belfast
Its currency is £
Program ended with exit code: 0

Summary

The above examples are just simple examples. If you wanted to do this in the real world, you wouldn’t do it this way. There is far too much duplicate code. But I hope it conveys the idea and functionality of namespaces.

Table of Contents

→ Index