8.8. Enumerated types

An enum (enumerated type) is a distinct type whose value is restricted to a range of values (see below for details), which may include several explicitly named constants ("enumerators"). The values of the constants are values of an integral type known as the underlying type of the enumeration.

There are two distinct kinds of enumerations:

unscoped enumeration

declared with the keyword enum

scoped enumeration

declared with the enum-key enum class or enum struct

8.8.1. Unscoped enumerations

Each enumerator becomes a named constant of the enumeration's type (that is, name), visible in the enclosing scope, and can be used whenever constants are required.

enum color { red, green, blue };
color r = red;
switch(r)
{
  case red  : std::cout << "red\n";   break;
  case green: std::cout << "green\n"; break;
  case blue : std::cout << "blue\n";  break;
}

Each enumerator is associated with a value of the underlying type. When initializers are provided in the enumerator-list, the values of enumerators are defined by those initializers. If the first enumerator does not have an initializer, the associated value is zero. For any other enumerator whose definition does not have an initializer, the associated value is the value of the previous enumerator plus one.

Values of unscoped enumeration type are implicitly-convertible to integral types. If the underlying type is not fixed, the value is convertible to the first type from the following list able to hold their entire value range: int, unsigned int, long, unsigned long, long long, or unsigned long long. If the underlying type is fixed, the values can be converted to their promoted underlying type.

enum color { red, yellow, green = 20, blue };
color c = red; // c  implicitly converts to 0
int n = blue;  // n == 21

Consider the following program:

Problems caused by unscoped enumerations

#include <iostream>

enum direction { north, south, east, west };

void show_direction(int direction) {
  std::cout << "Direction: " << direction << '\n';
}

int main() {
  direction dir = west;
  show_direction(dir);
  int num = dir;
  show_direction(num);

  for (int i = north; i < 8; ++i) {
    show_direction(i);
  }
}

What problems does this program have?

1. The unscoped enum direction is not type safe

   • Any integral type can be assigned to it

2. The line int num = dir; assigns a direction to an int

3. The for loop is unaware that there are only 4 directions, not 8.

4. Function show_direction implies it takes a direction as an argument, but any integral type will be processed without complaint

5. The function show_direction can't print a human readable direction. It can only print a number.

Scoped enums were introduced to address these specific shortcomings.

8.8.2. Scoped enumerations

Like unscoped enumerations, each enumerator becomes a named constant of the enumeration's type visible in the enclosing scope, and can be used whenever constants are required.

Unlike unscoped enums, scoped enums do not implicitly convert to integral types, but can be converted with a static or explicit cast.

enum class color { red, green = 20, blue };
color r = color::blue;
switch(r)
{
  case color::red  : std::cout << "red\n";   break;
  case color::green: std::cout << "green\n"; break;
  case color::blue : std::cout << "blue\n";  break;
}
// int n = r;                // error: no implicit int conversion
int n = static_cast<int>(r); // OK, n = 21

C++23 Feature

Starting in C++23, std::to_underlying provides a named standard-library function for the same conversion. These statements are equivalent:

std::to_underlying(color::red)

static_cast<int>(color::red)

All the C++ enumerated types are very simple compared to the same types in other languages. However, it is easy to add features as needed. Given the following scoped enum:

// If this were declared enum struct, nothing in this example changes...
//
enum class direction { north, south, east, west };

We can implement a stream overload to allow printing enum members with human readable strings:

std::ostream& operator<<(std::ostream& os, direction dir) {
  switch (dir) {
    case direction::north: return os << "north";
    case direction::east:  return os << "east";
    case direction::south: return os << "south";
    case direction::west:  return os << "west";
  }
  return os;
}

And an array allows the enum to be used in a range for loop:

constexpr std::array directions {
  direction::north,
  direction::east,
  direction::south,
  direction::west
};

Now the show directions program looks like this:

Printing and iterating scoped enum values

#include <array>
#include <iostream>

enum class direction { north, south, east, west };

std::ostream& operator<<(std::ostream& os, direction dir) {
  switch (dir) {
    case direction::north: return os << "north";
    case direction::east:  return os << "east";
    case direction::south: return os << "south";
    case direction::west:  return os << "west";
  }
  return os;
}

constexpr std::array directions {
  direction::north,
  direction::east,
  direction::south,
  direction::west
};

void show_direction(direction dir) {
  std::cout << "Direction: " << dir << '\n';
}

int main() {
  direction dir = direction::west;
  std::cout << "Show one direction:\n";
  show_direction(dir);

  std::cout << "Loop through all directions:\n";
  for (const auto dir: directions) {
    show_direction(dir);
  }
}

Another example uses the same techniques to build a deck of cards.

#include <array>
#include <iostream>
#include <vector>

enum class rank {
  ace = 1, two, three, four, five, six, seven, eight, nine, ten, jack, queen, king
};

// Define an array of rank to allow range-for looping
constexpr std::array ranks {
  rank::ace, rank::two, rank::three, rank::four, rank::five,
  rank::six, rank::seven, rank::eight, rank::nine, rank::ten,
  rank::jack, rank::queen, rank::king
};

enum class suit {
  clubs, diamonds, hearts, spades
};

// Define an array of suit to allow range-for looping
constexpr std::array suits {
  suit::clubs, suit::diamonds, suit::hearts, suit::spades
};

struct card {
  rank card_rank;
  suit card_suit;

  card(rank r, suit s)
    : card_rank{r},
      card_suit{s}
  {
  }
};

std::ostream& operator<<(std::ostream& os, rank value);
std::ostream& operator<<(std::ostream& os, suit value);
std::ostream& operator<<(std::ostream& os, const card& value);

// short, but take care . . .
// a change in the order of the enum could break this,
// Assumes order: A,2,3,4,5,6,7,8,9,10,J,Q,K
std::ostream& operator<<(std::ostream& os, rank value) {
  if (value > rank::ace && value < rank::jack) {
    os << static_cast<int>(value);
  } else if (value == rank::ace) {
    os << "Ace";
  } else if (value == rank::jack) {
    os << "Jack";
  } else if (value == rank::queen) {
    os << "Queen";
  } else {
    os << "King";
  }

  return os;
}

std::ostream& operator<<(std::ostream& os, suit value) {
  switch(value) {
    case suit::clubs:    os << "Clubs"; break;
    case suit::diamonds: os << "Diamonds"; break;
    case suit::hearts:   os << "Hearts"; break;
    case suit::spades:   os << "Spades"; break;
  }
  return os;
}

std::ostream& operator<<(std::ostream& os, const card& value) {
  return os << value.card_rank << " of " << value.card_suit;
}

int main() {
  std::vector<card> deck;
  for (const auto s: suits) {
    for (const auto r: ranks) {
      deck.emplace_back(r, s);
    }
  }
  for (const auto& c: deck) {
    std::cout << c << '\n';
  }
}

---

More to Explore

• From cppreference.com:

  • Enumeration declaration

  • std::to_underlying

• Enumeration (Microsoft)