Inspect and validate flag enums

To format flag enums or validate bitmask combinations in magic_enum, you must first opt-in the enum type by specializing magic_enum::customize::enum_range. Once enabled, you can use enum_flags_name to generate string representations of combined flags and enum_flags_contains to verify if a specific bitmask or string corresponds to valid flags.

Enable Flag Functionality

Before using flag-specific APIs, define the is_flags trait for your enum. This allows magic_enum to treat the enum as a bitmask rather than a simple list of values.

#include <iostream>
#include <magic_enum/magic_enum.hpp>
#include <magic_enum/magic_enum_flags.hpp>

enum class Settings : int {
  None = 0,
  OptionA = 1 << 0,
  OptionB = 1 << 1,
  OptionC = 1 << 2
};

// Specialize enum_range to enable flag support
template <>
struct magic_enum::customize::enum_range<Settings> {
  static constexpr bool is_flags = true;
};

int main() {
  using namespace magic_enum::bitwise_operators;
  Settings s = Settings::OptionA | Settings::OptionC;

  // enum_flags_name returns names joined by '|'
  std::cout << magic_enum::enum_flags_name(s) << std::endl; // Output: OptionA|OptionC
  
  return 0;
}

Validate Flag Combinations

Use magic_enum::enum_flags_contains to check if a value is a valid combination of the defined flags. This function supports enum values, raw integers, and string representations. When passing an integer or a string, you must explicitly provide the enum type as a template argument.

#include <cassert>
#include <magic_enum/magic_enum.hpp>
#include <magic_enum/magic_enum_flags.hpp>

enum class Color { RED = 1, GREEN = 2, BLUE = 4 };

template <>
struct magic_enum::customize::enum_range<Color> {
  static constexpr bool is_flags = true;
};

int main() {
  using namespace magic_enum::bitwise_operators;

  // Validate enum values
  assert(magic_enum::enum_flags_contains(Color::RED | Color::GREEN));
  assert(!magic_enum::enum_flags_contains(static_cast<Color>(8))); // 8 is not a valid flag

  // Validate raw integers (requires explicit template argument)
  assert(magic_enum::enum_flags_contains<Color>(3)); // 1 | 2 (RED | GREEN)
  assert(!magic_enum::enum_flags_contains<Color>(0)); // 0 is not considered a valid flag combination

  // Validate strings (requires explicit template argument)
  assert(magic_enum::enum_flags_contains<Color>("RED|BLUE"));
  assert(!magic_enum::enum_flags_contains<Color>("RED|YELLOW"));

  return 0;
}

Format Flag Names

The magic_enum::enum_flags_name function produces a std::string_view containing the names of all set flags, separated by the pipe (|) character. If the value contains bits that do not correspond to any defined flag, or if the value is 0, the function returns an empty string.

#include <iostream>
#include <string_view>
#include <magic_enum/magic_enum.hpp>
#include <magic_enum/magic_enum_flags.hpp>

enum class Permissions : uint32_t {
  Read = 1 << 0,
  Write = 1 << 1,
  Execute = 1 << 2
};

template <>
struct magic_enum::customize::enum_range<Permissions> {
  static constexpr bool is_flags = true;
};

int main() {
  using namespace magic_enum::bitwise_operators;

  Permissions p = Permissions::Read | Permissions::Write | Permissions::Execute;
  
  // Get formatted string
  std::string_view name = magic_enum::enum_flags_name(p);
  std::cout << "Permissions: " << name << std::endl; // Output: Read|Write|Execute

  // Invalid combinations return an empty string
  auto invalid = static_cast<Permissions>(1 << 10);
  assert(magic_enum::enum_flags_name(invalid).empty());

  return 0;
}