Inspect and validate flag enums

To inspect and validate flag enums in magic_enum, you must explicitly mark the enum as a flag type and use the specialized flag APIs. This allows magic_enum to correctly handle bitwise combinations of enum members when generating names or validating values.

Configure an Enum as Flags

Before using flag-specific functions, you must specialize magic_enum::customize::enum_range for your enum type and set is_flags to true. This informs magic_enum that the enum values represent bitmask flags.

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

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

// Explicitly mark the enum as a flag enum
template <>
struct magic_enum::customize::enum_range<Settings> {
  static constexpr bool is_flags = true;
};

Format Flag Combinations

Use magic_enum::enum_flags_name to get a string representation of a combination of flags. By default, it returns a string with flag names separated by the pipe (|) character. To use bitwise operators like | with scoped enums, bring magic_enum::bitwise_operators into scope.

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

using namespace magic_enum::bitwise_operators;

void print_settings(Settings s) {
  // Returns "OptionA|OptionB" for (OptionA | OptionB)
  std::string name = magic_enum::enum_flags_name(s);
  
  if (!name.empty()) {
    std::cout << "Active flags: " << name << std::endl;
  } else {
    std::cout << "No valid flags or out of range." << std::endl;
  }
}

Validate Flag Values

The magic_enum::enum_flags_contains function checks if a given value is a valid combination of the defined flags. It supports checking enum values, underlying integers, and string representations.

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

void validate() {
  using namespace magic_enum::bitwise_operators;

  // Check using enum value
  bool valid_enum = magic_enum::enum_flags_contains(Settings::OptionA | Settings::OptionC);
  assert(valid_enum == true);

  // Check using underlying integer
  bool valid_int = magic_enum::enum_flags_contains<Settings>(5); // 1 | 4 (OptionA | OptionC)
  assert(valid_int == true);

  // Check using string representation
  bool valid_str = magic_enum::enum_flags_contains<Settings>("OptionB|OptionC");
  assert(valid_str == true);
  
  // Invalid values return false
  assert(magic_enum::enum_flags_contains<Settings>(100) == false);
  assert(magic_enum::enum_flags_contains<Settings>("InvalidOption") == false);
}

Complete Example

This example demonstrates the full workflow: defining a flag enum, enabling bitwise operators, formatting a combination, and validating input.

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

enum class AnimalFlags : std::uint64_t {
  HasClaws  = 1 << 10,
  CanFly    = 1 << 20,
  EatsFish  = 1 << 30,
  Endangered = std::uint64_t{1} << 40
};

// Mark as flags
template <>
struct magic_enum::customize::enum_range<AnimalFlags> {
  static constexpr bool is_flags = true;
};

int main() {
  // Enable bitwise operators for AnimalFlags
  using namespace magic_enum::bitwise_operators;

  AnimalFlags bird = AnimalFlags::CanFly | AnimalFlags::HasClaws;

  // 1. Get formatted name
  // Output: "HasClaws|CanFly"
  std::cout << "Bird flags: " << magic_enum::enum_flags_name(bird) << std::endl;

  // 2. Validate combinations
  if (magic_enum::enum_flags_contains(bird)) {
    std::cout << "Bird has a valid flag combination." << std::endl;
  }

  // 3. Validate from string
  std::string input = "CanFly|EatsFish";
  if (magic_enum::enum_flags_contains<AnimalFlags>(input)) {
    std::cout << "'" << input << "' is a valid flag set." << std::endl;
  }

  return 0;
}

Troubleshooting

• Empty String from enum_flags_name: This occurs if the value contains bits that are not defined in the enum or if the enum was not correctly marked with is_flags = true.
• enum_flags_contains returns false for 0: In magic_enum, 0 is not considered a flag. If your enum includes a None = 0 member, enum_flags_contains will return false for it because it does not represent a set bit.
• Compilation Error on | operator: Ensure you have using namespace magic_enum::bitwise_operators; in the scope where you are combining flags.