Inspect and validate flag enums

To inspect and validate flag enums in magic_enum, you must explicitly enable flag semantics 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 represents a valid set of flags.

Enable Flag Semantics

By default, magic_enum treats enums as distinct values. To use bitwise combinations, you must set is_flags to true for your enum type.

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

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

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

Format Flag Combinations

The magic_enum::enum_flags_name function converts a bitwise combination of flags into a string. If multiple flags are set, it joins their names using a separator (defaulting to |).

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

// Assuming Color is defined and specialized as shown above
void print_color_name(Color c) {
  // Returns a string like "RED|GREEN"
  std::string name = magic_enum::enum_flags_name(c);
  
  if (!name.empty()) {
    std::cout << "Flags: " << name << std::endl;
  } else {
    // Returns empty string for 0 or invalid combinations
    std::cout << "Invalid or empty flags" << std::endl;
  }
}

Validate Flag Values

Use magic_enum::enum_flags_contains to check if a value is a valid combination of the defined flags. This function supports checking the enum type itself, the underlying integer, or a string representation.

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

// Validates if the combination exists in the reflected range
bool is_valid = magic_enum::enum_flags_contains(Color::RED | Color::GREEN); // true
bool is_invalid = magic_enum::enum_flags_contains(static_cast<Color>(8));   // false

// Validation via underlying integer
bool int_valid = magic_enum::enum_flags_contains<Color>(3); // true (RED | GREEN)

// Validation via string
bool string_valid = magic_enum::enum_flags_contains<Color>("RED|BLUE"); // true

Complete Example with Bitwise Operators

To combine flags using the | operator without manual casting, include magic_enum::bitwise_operators.

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

enum class Permissions : std::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;

  // Inspect name
  std::cout << magic_enum::enum_flags_name(p) << std::endl; // "Read|Write"

  // Validate combinations
  if (magic_enum::enum_flags_contains(p)) {
    std::cout << "Valid permission set." << std::endl;
  }

  // Check for specific flag
  if (magic_enum::enum_flags_contains<Permissions>("Read|Execute")) {
    std::cout << "Read and Execute are valid flags." << std::endl;
  }

  return 0;
}

Troubleshooting

• Empty String Output: magic_enum::enum_flags_name returns an empty string if the value is 0 or if it contains bits that do not correspond to any defined enumerator.
• Validation Failure: magic_enum::enum_flags_contains returns false for a value of 0 because 0 is not considered a flag in the magic_enum implementation.
• Compilation Errors with |: Ensure you have using namespace magic_enum::bitwise_operators; in the scope where you are combining flags, otherwise the compiler will not find the overloaded operators for scoped enums.