Inspect and validate flag enums

To inspect and validate bitwise combinations of enum values in magic_enum, you must first enable flag support for your enum type. 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 enums as single-value types. To use flag-specific APIs, you must specialize magic_enum::customize::enum_range for your type and set is_flags to true.

#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
};

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

Format Flag Enums as Strings

The magic_enum::enum_flags_name function converts a bitwise-ORed combination of flags into a string. By default, it uses the pipe character (|) as a separator, but you can provide a custom character.

using namespace magic_enum;

auto flags = AnimalFlags::CanFly | AnimalFlags::EatsFish;

// Default separator '|'
// Returns "CanFly|EatsFish"
std::string name = enum_flags_name(flags);

// Custom separator ','
// Returns "CanFly,EatsFish"
std::string custom_name = enum_flags_name(flags, ',');

If the value is 0 or contains bits that do not correspond to any defined enumerator, enum_flags_name returns an empty string.

Validate Flag Combinations

Use magic_enum::enum_flags_contains to check if a value (enum, integer, or string) is a valid combination of defined flags.

Validating Enum and Integer Values

A value is considered valid if it is non-zero and composed entirely of defined flag bits.

// Valid combination
bool valid = magic_enum::enum_flags_contains(AnimalFlags::HasClaws | AnimalFlags::CanFly); // true

// Invalid: contains undefined bit (e.g., bit 0)
bool invalid_bit = magic_enum::enum_flags_contains(static_cast<AnimalFlags>(1)); // false

// Invalid: zero is not considered a valid flag combination
bool invalid_zero = magic_enum::enum_flags_contains(static_cast<AnimalFlags>(0)); // false

Validating String Representations

You can also validate if a string correctly names a set of flags. This supports custom separators and case-insensitive matching via a predicate.

// Valid string
bool valid_str = magic_enum::enum_flags_contains<AnimalFlags>("CanFly|EatsFish"); // true

// Case-insensitive validation with custom separator
bool ci_valid = magic_enum::enum_flags_contains<AnimalFlags>(
    "canfly,eatsfish", 
    ',', 
    [](char lhs, char rhs) {
        return std::tolower(lhs) == std::tolower(rhs);
    }
); // true

// Invalid: contains an unknown name
bool unknown_str = magic_enum::enum_flags_contains<AnimalFlags>("CanFly|Unknown"); // false

Troubleshooting and Behavior

Zero Values: Both enum_flags_name and enum_flags_contains treat 0 as an invalid value. enum_flags_name returns an empty string, and enum_flags_contains returns false.
String Order: The string returned by enum_flags_name follows the declaration order of the enumerators in the source code, regardless of the order in which flags were combined in the variable.
Partial Matches: If a bitwise combination contains even one bit that is not defined in the enum, enum_flags_name will return an empty string and enum_flags_contains will return false.
Required Header: These functions are defined in magic_enum/magic_enum_flags.hpp. Ensure this is included in addition to the base magic_enum.hpp.

Enable Flag Support​

Format Flag Enums as Strings​

Validate Flag Combinations​

Validating Enum and Integer Values​

Validating String Representations​