Inspect and validate flag enums

To inspect and validate bitwise flag combinations in magic_enum, you must first mark your enum as a flags enum by specializing magic_enum::customize::enum_range. Once enabled, you can use magic_enum::enum_flags_name to generate string representations of combined flags and magic_enum::enum_flags_contains to verify if a value or string represents a valid set of flags.

Enable flag enum support

Before using flag-specific APIs, specialize magic_enum::customize::enum_range for your enum type and set is_flags to true. This tells magic_enum to treat the enum as a bitmask where multiple values can be combined.

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

enum class Status : int {
  None = 0,
  Active = 1 << 0,
  Pending = 1 << 1,
  Deleted = 1 << 2
};

// Specialization required for flag-based reflection
template <>
struct magic_enum::customize::enum_range<Status> {
  static constexpr bool is_flags = true;
};

int main() {
  using namespace magic_enum::bitwise_operators; // Enable operator| for Status
  
  Status s = Status::Active | Status::Pending;
  
  // enum_flags_name returns "Active|Pending"
  std::cout << magic_enum::enum_flags_name(s) << std::endl;
  
  return 0;
}

Format flag combinations

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

#include <iostream>
#include <string>
#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;

  // Single flag
  auto n1 = magic_enum::enum_flags_name(Color::Red); // "Red"
  
  // Combined flags
  auto n2 = magic_enum::enum_flags_name(Color::Red | Color::Blue); // "Red|Blue"
  
  // Invalid or zero values return empty string
  auto n3 = magic_enum::enum_flags_name(static_cast<Color>(0)); // ""
  auto n4 = magic_enum::enum_flags_name(static_cast<Color>(8)); // ""

  return 0;
}

Validate flag values and strings

The magic_enum::enum_flags_contains function checks if a given input represents a valid combination of flags. When passing an underlying integer or a string, you must explicitly provide the enum type as a template argument.

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

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

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

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

  // 1. Validate using enum type
  bool b1 = magic_enum::enum_flags_contains(Permission::Read | Permission::Write); // true
  
  // 2. Validate using underlying integer (requires template argument)
  bool b2 = magic_enum::enum_flags_contains<Permission>(3); // true (Read | Write)
  bool b3 = magic_enum::enum_flags_contains<Permission>(8); // false (Undefined bit)
  
  // 3. Validate using string (requires template argument)
  bool b4 = magic_enum::enum_flags_contains<Permission>("Read|Execute"); // true
  bool b5 = magic_enum::enum_flags_contains<Permission>("Read|Invalid"); // false

  // Note: 0 is not considered a valid flag combination
  bool b6 = magic_enum::enum_flags_contains<Permission>(0); // false

  return 0;
}

Troubleshooting

• Empty strings from enum_flags_name: This occurs if the value is 0 or if it contains any bit that is not mapped to a named enumerator in the enum definition.
• Bitwise operators not working: Ensure you have using namespace magic_enum::bitwise_operators; in the scope where you use |, &, ~, or ^ with scoped enums.
• Template deduction failure: magic_enum::enum_flags_contains cannot deduce the enum type from a raw integer or a string. You must call it as enum_flags_contains<MyEnum>(val).
• Missing specialization: If you forget to specialize magic_enum::customize::enum_range<E>::is_flags = true, these functions will not correctly identify bitwise combinations and may treat the enum as a standard sequential enum.