Namespaces

When working with bigger projects, or importing additional third-party code using the #include directive, we can run into further organization problems.

When we use a class like Character or call a function like CalculateArea() it can be unclear where that identifier is coming from.

Additionally, the larger our project becomes, the more likely it is we have conflicts around these identifiers. We'll have scenarios where multiple variables, functions, or classes use the same name.

The way this problem is solved is by the introduction of namespaces.

Creating a Namespace

We can wrap sections of our code inside a namespace as shown below. Here, we create a namespace called Geometry:

1namespace Geometry {
2  // your code here
3}

We can populate namespaces with classes, functions, variables, and any of the constructs we've seen before:

1namespace Geometry {
2  float Add(float x, float y) {
3    return x + y;
4  }
5
6  float Pi { 3.14 };
7
8  class Square {
9    float SideLength { 5.0 };
10    float Area() {
11      return SideLength * SideLength;
12    }
13  };
14}

Accessing Identifiers Inside Namespaces

As usual with { and }, namespaces define a new scope. Expressions within the namespace can access other namespace members as usual:

1namespace Geometry {
2  float Pi { 3.14 };
3  float Circumference(float Diameter) {
4    // We can access Pi here as we're in
5    // the same scope / namespace
6    return Diameter * Pi;
7  }
8}

To access namespace members from outside the namespace, we need the Scope Resolution Operator, which has two colons ::

For example, the following statement accesses the Add function and the Pi variable, which are both inside the Geometry namespace:

1namespace Geometry {
2  float Add(float x, float y) {
3    return x + y;
4  }
5
6  float Pi { 3.14 };
7}
8
9int main() {
10  Geometry::Add(10, Geometry::Pi);
11}

1namespace Utilities {
2  void Greet() {
3    cout << "Hi!";
4  };
5};

Nested Namespaces

Namespaces can be nested inside other namespaces. Below, we have a namespace called Constants within a namespace called Geometry:

1namespace Geometry {
2  float Add(float x, float y) {
3    return x + y;
4  }
5  namespace Constants {
6    float Pi { 3.14f };
7  }
8}

To access these nested identifiers, we can use the :: operator multiple times:

1Geometry::Add(10, Geometry::Constants::Pi)

The One Definition Rule (ODR)

Once we create a namespace and #include it in other files, we'll quickly begin to see linker errors relating to symbols already being defined. The following simple 3-file program recreates this:

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  float Pi{3.14};
6  float Circumference(float Diameter) {
7    return Diameter * Pi;
8  }
9}

1// main.cpp
2#include "Geometry.h"
3
4int main() {}

1// SomeFile.cpp
2#include "Geometry.h"

1main.cpp.obj : error LNK2005: "float Geometry::Circumference(float)" already defined in SomeFile.obj
2main.cpp.obj : error LNK2005: "float Geometry::Pi" already defined in SomeFile.obj

To solve this, we can split our namespace into a header file and source file, in much the same way we have shown with classes.

Our declarations remain in Geometry.h whilst we move definitions to Geometry.cpp, as in the following example. Note we explain the meaning of extern in the next section:

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  extern float Pi;
6  float Circumference(float Diameter);
7}

1// Geometry.cpp
2#include "Geometry.h"
3
4float Geometry::Pi{3.14};
5float Geometry::Circumference(float Diameter) {
6  return Diameter * Pi;
7}

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  inline float Pi{3.14};
6  inline float Circumference(float Diameter) {
7    return Diameter * Pi;
8  }
9}

1// Character.h
2#pragma once
3
4class Character {
5public:
6  int Health{100}
7};

Adding to Namespaces

In large projects, namespaces can get quite large. They can include multiple classes, for example. As such, it is common for the contents of a namespace to span multiple files.

Below, we create a namespace containing two classes, where each class is declared within a dedicated file:

1// Square.h 
2#pragma once
3
4namespace Geometry {
5  class Square{};
6}

1// Circle.h 
2#pragma once
3
4namespace Geometry {
5  class Circle{};
6}

1// main.cpp
2#include "Circle.h"
3#include "Square.h"
4
5int main() {
6  Geometry::Circle MyCircle;
7  Geometry::Square MySquare;
8}

Where we're providing a full declaration of our namespace within a header file, we can alternatively provide class definitions by including that header file and then using the :: operator like this:

1// Geometry.h
2#pragma once
3
4namespace Geometry {
5  class Circle;
6}

1// Circle.h
2#pragma once
3#include "Geometry.h"
4
5class Geometry::Circle {
6
7};

When our class is within a namespace, our source files for that class can provide function definitions using either the namespace syntax, or the :: operator:

1// Square.h
2#pragma once
3
4namespace Geometry {
5  class Square{
6   public:
7    float Area();
8    float Perimeter();
9
10  private:
11    float SideLength;
12  };
13}

1// Square.cpp
2#include "Square.h"
3
4// Option 1:
5namespace Geometry {
6  float Square::Area() {
7    return SideLength * SideLength;
8  }
9}
10
11// Option 2:
12float Geometry::Square::Perimeter() {
13  return SideLength * 4;
14}

Anonymous Namespaces

Previously, we introduced the concept of global variables. These are variables that are added to our files, outside of any scope. In the following example, Pi is a global variable:

1// main.cpp
2float Pi;
3
4int main() {}

We saw how the linker can link a definition in one file to its use in another.

However, this presents a problem when there are multiple definitions of the same identifier.

For example, if we create a global Pi variable in another file, our program will no longer link correctly:

1// Geometry.cpp
2float Pi;

1main.cpp.obj : error LNK2005: "float Pi"
2already defined in Geometry.obj

This is again a violation of the one-definition rule (ODR).

If we intend to forward-declare a variable that will be defined in some other file, we can add the extern keyword as described above:

1// Geometry.cpp
2float Pi { 3.1415 };

1// main.cpp
2#include <iostream>
3using namespace std;
4
5extern float Pi;
6
7int main() {
8  cout << "Pi as defined in some other file: "
9    << Pi;
10}

1Pi as defined in some other file: 3.1415

If we intend to create a variable that we can use anywhere in the current file, without affecting any other file, we can solve the problem using an anonymous namespace.

Predictably, an anonymous namespace is a namespace without a name:

1namespace {
2  float Pi { 3.14 };
3}

Identifiers defined within an anonymous namespace are only available to the same source file where the namespace exists.

Therefore, we can think of an anonymous namespace as the "private" section of a file.

1// Geometry.cpp
2namespace {
3  float Pi{3.1415};
4}
5
6float GetPi() { return Pi; }

1// main.cpp
2#include <iostream>
3using namespace std;
4
5namespace {
6  float Pi{3.14};
7}
8
9// Forward declaring a function defined
10// in Geometry.cpp
11float GetPi();
12
13int main() {
14  cout << "Pi in main.cpp: " << Pi
15    << "\nPi in Geometry.cpp: " << GetPi();
16}

1Pi in main.cpp: 3.14
2Pi in Geometry.cpp: 3.1415

Summary

This lesson provided an introduction to namespaces, covering their creation, usage, and significance in organizing code.

Key Takeaways:

• How to create and use namespaces to organize code and avoid identifier conflicts.
• The role of the scope resolution operator :: in accessing namespace members.
• The concept of nested namespaces and how they can be used for further organization.
• The importance of the One Definition Rule (ODR) in namespaces and strategies to adhere to it using the extern and inline keywords.
• The distinction between namespaces and classes in C++, and the introduction to anonymous namespaces for file-specific usage.

Preview of the Next Lesson

In our next lesson, we'll delve into the world of enums. Enums, or enumerations, are yet another way to create user-defined types, but they are much simpler than classes and structs.

They are particularly useful in scenarios when we need to create variables that have a value from a limited range of possibilities, which we can define.

Key Topics:

• Understanding the basic concept of enums and their role in programming.
• Learning how to define and use enums to represent a collection of related values.
• Exploring the benefits of using enums for code readability and maintenance.

Free and Unlimited Access

Professional C++

Unlock the true power of C++ by mastering complex features, optimizing performance, and learning expert workflows used in professional development

View Course