Skip to main content

magic_enum

C++ API reference for the namespace magic_enum.

Public API​

Free Function: enum_flags_cast​

Canonical path: magic_enum::enum_flags_cast

Declared in: include/magic_enum/magic_enum_flags.hpp

Signatures​

Overload 1​
[[nodiscard]] constexpr auto enum_flags_cast(string_view value, [[maybe_unused]] char_type sep = char_type{'|'}, [[maybe_unused]] BinaryPredicate p = {}) noexcept(detail::is_nothrow_invocable_v<BinaryPredicate>) -> detail::enable_if_t<E, optional<std::decay_t<E>>, BinaryPredicate>;

Summary

Converts a string representation of enum flags into their corresponding enum value.

Behavior

The function parses a string of flag names separated by a delimiter, accumulating the underlying values of matched flags using bitwise OR. It returns an empty optional if the enum has no reflected flags, if any substring between delimiters does not match a known flag name, or if the final result is zero.

Parameters

  • value: A string_view containing one or more flag names separated by a delimiter.

Returns

  • Return value 1: Returns an optional containing the combined enum value if parsing succeeds, otherwise returns an empty optional.
Overload 2​
[[nodiscard]] constexpr auto enum_flags_cast(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, optional<std::decay_t<E>>>;

Summary

Casts an underlying integer value to an optional enum value if it represents valid flags.

Behavior

The function validates if the provided underlying value represents a valid combination of flags for the enum. If the enum is sparse, it checks if the value is exactly composed of reflected flag bits. If not sparse, it checks if the value falls within the range between the minimum flag and the bitwise OR of all reflected values.

Parameters

  • value: The underlying integer value to be cast to the enum type.

Returns

  • Return value 1: Returns an optional containing the enum value if the input is valid, otherwise returns an empty optional.

Free Function: enum_flags_contains​

Canonical path: magic_enum::enum_flags_contains

Declared in: include/magic_enum/magic_enum_flags.hpp

Signatures​

Overload 1​
[[nodiscard]] constexpr auto enum_flags_contains(E value) noexcept -> detail::enable_if_t<E, bool>;

Summary

Checks if the given enum value is a valid combination of flags.

Behavior

The function converts the enum value to its underlying type and checks if it can be successfully cast back to a valid flag combination using enum_flags_cast.

Parameters

  • value: The enum value to check for validity as a flag combination.

Returns

  • Return value 1: Returns true if the value represents a valid combination of flags, false otherwise.
Overload 2​
[[nodiscard]] constexpr auto enum_flags_contains(string_view value, char_type sep = char_type{'|'}, BinaryPredicate p = {}) noexcept(detail::is_nothrow_invocable_v<BinaryPredicate>) -> detail::enable_if_t<E, bool, BinaryPredicate>;

Summary

Checks if a string representation of flags corresponds to a valid enum value.

Behavior

The function attempts to cast the string representation to an enum value using enum_flags_cast and returns whether the resulting optional has a value.

Parameters

  • value: A string_view containing flag names to validate.

Returns

  • Return value 1: Returns true if the string successfully parses into a valid flag combination, false otherwise.
Overload 3​
[[nodiscard]] constexpr auto enum_flags_contains(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, bool>;

Summary

Checks if an underlying integer value represents a valid combination of enum flags.

Behavior

The function checks if the provided underlying value is a valid flag combination by attempting to cast it using enum_flags_cast.

Parameters

  • value: The underlying integer value to validate.

Returns

  • Return value 1: Returns true if the underlying value is a valid flag combination, false otherwise.

Free Function: enum_flags_name​

Canonical path: magic_enum::enum_flags_name

Declared in: include/magic_enum/magic_enum_flags.hpp

Signature​

[[nodiscard]] auto enum_flags_name(E value, char_type sep = char_type{'|'}) -> detail::enable_if_t<E, string>;

Summary

Retrieves the string representation of the flags set in an enum value.

Behavior

The function iterates through reflected flags, performing a bitwise AND between the input value and each flag. If a match is found, the flag's name is appended to the result string, separated by the specified delimiter. It returns an empty string if any matched flag has an empty name or if the input value is not fully accounted for by reflected flags.

Parameters

  • value: The enum value whose flag names are to be retrieved.

Returns

  • Return value 1: Returns a string containing the names of the flags present in the value, or an empty string if the value is invalid or out of range.

Free Function: enum_flags_test​

Canonical path: magic_enum::enum_flags_test

Declared in: include/magic_enum/magic_enum_flags.hpp

Signature​

constexpr auto enum_flags_test(E flags, E flag) noexcept -> detail::enable_if_t<E, bool>;

Summary

Tests if a specific flag or set of flags is contained within another enum flag value.

Behavior

The function checks if the underlying value of flag is non-zero and if all bits set in flag are also set in flags using bitwise AND.

Parameters

  • flags: The enum value representing the set of flags to check against.
  • flag: The specific flag or combination of flags to look for within the flags parameter.

Returns

  • Return value 1: Returns true if all bits in flag are present in flags and flag is not zero, false otherwise.

Free Function: enum_flags_test_any​

Canonical path: magic_enum::enum_flags_test_any

Declared in: include/magic_enum/magic_enum_flags.hpp

Signature​

constexpr auto enum_flags_test_any(E lhs, E rhs) noexcept -> detail::enable_if_t<E, bool>;

Summary

Tests if two enum flag sets share any common flags.

Behavior

The function performs a bitwise AND between the underlying values of the two inputs and checks if the result is non-zero.

Parameters

  • lhs: The left-hand side enum value for the comparison.
  • rhs: The right-hand side enum value for the comparison.

Returns

  • Return value 1: Returns true if any bits are set in both lhs and rhs, false otherwise.