Inspect and validate flag enums

To inspect and validate flag-enabled enumerations in magic_enum, you must first enable flag support by specializing the magic_enum::customize::enum_range template. Once enabled, you can use enum_flags_name to generate string representations of combined flags and enum_flags_contains to verify if a value or string represents a valid set of flags.

Enable flag support

By default, magic_enum treats enumerations as single-value types. To use flag-specific APIs, specialize magic_enum::customize::enum_range<T> for your enum type and set is_flags to true.

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

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

// Enable flag support for Color
template <>
struct magic_enum::customize::enum_range<Color> {
  static constexpr bool is_flags = true;
};

int main() {
  using namespace magic_enum::bitwise_operators;
  Color flags = Color::RED | Color::BLUE;
  
  // enum_flags_name returns a '|'-separated string
  std::cout << magic_enum::enum_flags_name(flags) << std::endl; // Output: RED|BLUE
  
  return 0;
}

Format flag names

The magic_enum::enum_flags_name function returns a std::string_view for single flags or a std::string for combined flags. If a value contains bits that do not correspond to any named flag in the enumeration, the function returns an empty string.

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

enum class Permissions { Read = 1, Write = 2, Execute = 4 };

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

int main() {
  using namespace magic_enum::bitwise_operators;
  
  // Single flag
  std::cout << magic_enum::enum_flags_name(Permissions::Read) << std::endl; // "Read"
  
  // Combined flags
  auto combined = Permissions::Read | Permissions::Write | Permissions::Execute;
  std::cout << magic_enum::enum_flags_name(combined) << std::endl; // "Read|Write|Execute"
  
  // Invalid combination (contains bit 8 which is not defined)
  auto invalid = static_cast<Permissions>(1 | 8);
  if (magic_enum::enum_flags_name(invalid).empty()) {
    std::cout << "Invalid flag combination detected" << std::endl;
  }
  
  return 0;
}

Validate flag values and strings

The magic_enum::enum_flags_contains function checks if a value is a valid member or a valid combination of members for a flag enum. When passing an underlying integer or a string, you must explicitly provide the enum type as a template argument.

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

enum class Status { Active = 1, Pending = 2, Deleted = 4 };

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

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

  // 1. Check using enum value
  bool v1 = magic_enum::enum_flags_contains(Status::Active | Status::Pending); // true
  
  // 2. Check using underlying integer (requires explicit template argument)
  bool v2 = magic_enum::enum_flags_contains<Status>(3); // true (1 | 2)
  bool v3 = magic_enum::enum_flags_contains<Status>(8); // false (not defined)

  // 3. Check using string (requires explicit template argument)
  bool v4 = magic_enum::enum_flags_contains<Status>("Active|Pending"); // true
  bool v5 = magic_enum::enum_flags_contains<Status>("Active|Unknown"); // false

  std::cout << std::boolalpha << v1 << " " << v2 << " " << v3 << " " << v4 << " " << v5 << std::endl;
  
  return 0;
}