magic_enum
C++ API reference for the namespace magic_enum.
Public API
Free Function: enum_cast
Canonical path: magic_enum::enum_cast
Declared in: include/magic_enum/magic_enum.hpp
Signatures
Overload 1
[[nodiscard]] constexpr auto enum_cast(string_view value, [[maybe_unused]] BinaryPredicate p = {}) noexcept(detail::is_nothrow_invocable_v<BinaryPredicate>) -> detail::enable_if_t<E, optional<std::decay_t<E>>, BinaryPredicate>;
Summary
Obtains an enum value from its string name.
Behavior
Searches for an enum value whose name matches the provided string using a predicate. If MAGIC_ENUM_ENABLE_HASH is defined and a default predicate is used, it employs a constexpr switch; otherwise, it performs a linear search through reflected enum names.
Parameters
- value: The string representation of the enum constant to cast.
Returns
- Return value 1: An optional containing the enum value if a match is found, otherwise an empty optional.
Overload 2
[[nodiscard]] constexpr auto enum_cast(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, optional<std::decay_t<E>>>;
Summary
Obtains an enum value from its underlying integer representation.
Behavior
Validates if the underlying value corresponds to a reflected enum member. For sparse or flag enums, it checks against all reflected values (potentially using a constexpr switch if hashing is enabled). For dense enums, it performs a range check against minimum and maximum values.
Parameters
- value: The underlying integer value to cast to an enum.
Returns
- Return value 1: An optional containing the enum value if valid, otherwise an empty optional.
Free Function: enum_contains
Canonical path: magic_enum::enum_contains
Declared in: include/magic_enum/magic_enum.hpp
Signatures
Overload 1
[[nodiscard]] constexpr auto enum_contains(E value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks whether the enum contains the specified value.
Behavior
Checks if the provided enum value is valid by attempting to cast its underlying value using enum_cast.
Parameters
- value: The enum value to check for validity.
Returns
- Return value 1: True if the value is a valid reflected enum member, false otherwise.
Overload 2
[[nodiscard]] constexpr auto enum_contains(E value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks whether the enum contains the specified value using an explicit subtype.
Behavior
Determines if an enum value is valid by casting it to its underlying type and calling enum_cast with the specified subtype.
Parameters
- value: The enum value to validate.
Returns
- Return value 1: True if the value is valid within the specified enum subtype, false otherwise.
Overload 3
[[nodiscard]] constexpr auto enum_contains(string_view value, BinaryPredicate p = {}) noexcept(detail::is_nothrow_invocable_v<BinaryPredicate>) -> detail::enable_if_t<E, bool, BinaryPredicate>;
Summary
Checks whether the enum contains a member with the specified string name.
Behavior
Invokes enum_cast with the provided string and predicate to determine if a match exists.
Parameters
- value: The string name to search for.
Returns
- Return value 1: True if a matching enum name is found, false otherwise.
Overload 4
[[nodiscard]] constexpr auto enum_contains(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks whether the enum contains a member with the specified underlying value.
Behavior
Calls enum_cast with the underlying integer value to verify its existence in the enum reflection.
Parameters
- value: The underlying integer value to check.
Returns
- Return value 1: True if the integer corresponds to a valid enum member, false otherwise.
Free Function: enum_count
Canonical path: magic_enum::enum_count
Declared in: include/magic_enum/magic_enum.hpp
Signature
[[nodiscard]] constexpr auto enum_count() noexcept -> detail::enable_if_t<E, std::size_t>;
Summary
Returns the number of enum values.
Behavior
Retrieves the count of enum members from the internal reflection detail count_v.
Returns
- Return value 1: The number of enumerated values in the specified enum type.
Free Function: enum_entries
Canonical path: magic_enum::enum_entries
Declared in: include/magic_enum/magic_enum.hpp
Signature
[[nodiscard]] constexpr auto enum_entries() noexcept -> detail::enable_if_t<E, detail::entries_t<E, S>>;
Summary
Returns a collection of all enum entries.
Behavior
Ensures the enum is reflected via static_assert and returns the internal entries_v containing value-name pairs.
Returns
- Return value 1: A collection of all enum entries (value and name pairs).
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]] BinaryPredicate p = {}) noexcept(detail::is_nothrow_invocable_v<BinaryPredicate>) -> detail::enable_if_t<E, optional<std::decay_t<E>>, BinaryPredicate>;
Summary
Obtains a flag enum value from a string of pipe-separated names.
Behavior
Parses a string containing pipe-separated ('|') flag names. It iterates through the string, finds each segment, and performs a linear search against reflected flag names to combine their underlying values using bitwise OR.
Parameters
- value: A string containing one or more flag names separated by '|'.
Returns
- Return value 1: An optional containing the combined flag enum value if all names are valid, otherwise 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
Obtains a flag enum value from its underlying integer bitmask.
Behavior
Validates a bitmask value. For sparse enums, it iterates through reflected values to ensure every set bit in the input corresponds to a known flag. For non-sparse enums, it checks if the value is within the range of the minimum and the bitwise OR of all valid flags.
Parameters
- value: The underlying integer bitmask to validate.
Returns
- Return value 1: An optional containing the flag enum value if the bitmask is valid, otherwise 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 whether the flag enum contains the specified bitmask value.
Behavior
Casts the enum value to its underlying type and calls enum_flags_cast to verify if the bitmask is valid.
Parameters
- value: The flag enum value to check.
Returns
- Return value 1: True if the value represents a valid combination of flags, false otherwise.
Overload 2
[[nodiscard]] constexpr auto enum_flags_contains(string_view value, BinaryPredicate p = {}) noexcept(detail::is_nothrow_invocable_v<BinaryPredicate>) -> detail::enable_if_t<E, bool, BinaryPredicate>;
Summary
Checks whether the flag enum contains the flags specified by the string.
Behavior
Attempts to cast the provided string of flag names using enum_flags_cast and returns the success status.
Parameters
- value: The pipe-separated string of flag names.
Returns
- Return value 1: True if the string represents a valid set of flag names, false otherwise.
Overload 3
[[nodiscard]] constexpr auto enum_flags_contains(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks whether the flag enum contains the specified underlying bitmask value.
Behavior
Calls enum_flags_cast with the underlying integer to determine if the bitmask is valid for the enum.
Parameters
- value: The underlying integer bitmask to check.
Returns
- Return value 1: True if the bitmask is valid for the flag enum, 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 = static_cast<char_type>('|')) -> detail::enable_if_t<E, string>;
Summary
Retrieves a string representation of the flags set in an enum value.
Behavior
Iterates through the reflected flags of the enum type, appending the name of each flag present in the value to a string separated by the provided character.
Parameters
- value: The enum value containing the flags to be named.
Returns
- Return value 1: 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 is set within an enum bitmask.
Behavior
Checks if all bits set in the flag parameter are also set in the flags parameter using bitwise operations.
Parameters
- flags: The enum value representing the set of flags to check against.
- flag: The specific flag or flags to look for within the flags parameter.
Returns
- Return value 1: True if the flag is non-zero and all its bits are present in flags, 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 values share any common bits.
Behavior
Performs a bitwise AND between the underlying values of two enum instances and checks if the result is non-zero.
Parameters
- lhs: The left-hand side enum value for the bitwise comparison.
- rhs: The right-hand side enum value for the bitwise comparison.
Returns
- Return value 1: True if any bits are shared between the two enum values, false otherwise.
Free Function: enum_for_each
Canonical path: magic_enum::enum_for_each
Declared in: include/magic_enum/magic_enum_utility.hpp
Signature
constexpr auto enum_for_each(F&& f);
Summary
Iterates over all values of an enum and applies a function to each.
Behavior
Invokes the provided function object for every reflected value of the specified enum type.
Parameters
- f: The invocable function object to be called for each enum value.
Returns
- Return value 1: The result of the internal for_each utility call.
Free Function: enum_fuse
Canonical path: magic_enum::enum_fuse
Declared in: include/magic_enum/magic_enum_fuse.hpp
Signature
[[nodiscard]] constexpr auto enum_fuse(Es... values) noexcept;
Summary
Fuses multiple enum values into a single value.
Behavior
Combines multiple enum values into a single fused representation, asserting that at least two values are provided and the combined bit width is supported.
Returns
- Return value 1: The fused enum value generated by either typesafe or non-typesafe internal implementation.
Free Function: enum_index
Canonical path: magic_enum::enum_index
Declared in: include/magic_enum/magic_enum.hpp
Signatures
Overload 1
[[nodiscard]] constexpr auto enum_index() noexcept -> detail::enable_if_t<decltype(V), std::size_t>;
Summary
Obtains the index of a constant enum value at compile time.
Behavior
Retrieves the index of a compile-time constant enum value by looking it up in the reflected enum metadata.
Returns
- Return value 1: The zero-based index of the enum value.
Overload 2
[[nodiscard]] constexpr auto enum_index(E value) noexcept -> detail::enable_if_t<E, optional<std::size_t>>;
Summary
Retrieves the index of an enum value.
Behavior
Calculates the index of an enum value, using a switch or loop for sparse/flag enums, or direct arithmetic for dense enums.
Parameters
- value: The enum value to find the index for.
Returns
- Return value 1: An optional containing the index if the value is valid, otherwise an empty optional.
Overload 3
[[nodiscard]] constexpr auto enum_index(E value) noexcept -> detail::enable_if_t<E, optional<std::size_t>>;
Summary
Retrieves the index of an enum value with an explicit subtype.
Behavior
Delegates the index lookup to the primary enum_index implementation for the specified enum type and subtype.
Parameters
- value: The enum value to look up.
Returns
- Return value 1: An optional containing the index of the value if found.
Free Function: enum_integer
Canonical path: magic_enum::enum_integer
Declared in: include/magic_enum/magic_enum.hpp
Signature
[[nodiscard]] constexpr auto enum_integer(E value) noexcept -> underlying_type_t<E>;
Summary
Converts an enumeration value to its underlying integer type.
Behavior
The function performs a static cast of the input value to its underlying type.
Parameters
- value: An enumeration value of type E.
Returns
- Return value 1: The underlying type of the enumeration E.
Free Function: enum_name
Canonical path: magic_enum::enum_name
Declared in: include/magic_enum/magic_enum.hpp
Signatures
Overload 1
[[nodiscard]] constexpr auto enum_name() noexcept -> detail::enable_if_t<decltype(V), string_view>;
Summary
Obtains the name of a constant enum value at compile time.
Behavior
Retrieves the string name of a compile-time constant enum value from reflected metadata.
Returns
- Return value 1: A string view representing the name of the enum value.
Overload 2
[[nodiscard]] constexpr auto enum_name(E value) noexcept -> detail::enable_if_t<E, string_view>;
Summary
Retrieves the name of an enum value.
Behavior
Looks up the index of the provided enum value and returns its corresponding name from the reflected metadata.
Parameters
- value: The enum value whose name is to be retrieved.
Returns
- Return value 1: A string view of the enum name, or an empty string view if the value is not found.
Overload 3
[[nodiscard]] constexpr auto enum_name(E value) -> detail::enable_if_t<E, string_view>;
Summary
Retrieves the name of an enum value with an explicit subtype.
Behavior
Calls the primary enum_name implementation using the specified enum type and subtype.
Parameters
- value: The enum value to look up.
Returns
- Return value 1: A string view of the enum name.
Free Function: enum_names
Canonical path: magic_enum::enum_names
Declared in: include/magic_enum/magic_enum.hpp
Signature
[[nodiscard]] constexpr auto enum_names() noexcept -> detail::enable_if_t<E, detail::names_t<E, S>>;
Summary
Retrieves the names of all values in an enum.
Behavior
Accesses the reflected array of names for the specified enum type and subtype.
Returns
- Return value 1: A collection containing the names of all reflected enum values.
Free Function: enum_next_value
Canonical path: magic_enum::enum_next_value
Declared in: include/magic_enum/magic_enum_utility.hpp
Signature
[[nodiscard]] constexpr auto enum_next_value(E value, std::ptrdiff_t n = 1) noexcept -> detail::enable_if_t<E, optional<std::decay_t<E>>>;
Summary
Retrieves the next enum value relative to a given value.
Behavior
Calculates the index of the current value and returns the value at the new index offset by n, provided the resulting index is within the valid range of reflected values.
Parameters
- value: The starting enum value.
Returns
- Return value 1: An optional containing the enum value at the offset position, or an empty optional if the index is out of bounds or the input value is invalid.
Free Function: enum_next_value_circular
Canonical path: magic_enum::enum_next_value_circular
Declared in: include/magic_enum/magic_enum_utility.hpp
Signature
[[nodiscard]] constexpr auto enum_next_value_circular(E value, std::ptrdiff_t n = 1) noexcept -> detail::enable_if_t<E, std::decay_t<E>>;
Summary
Retrieves the next enum value with circular wrapping.
Behavior
Calculates the index of the current value and returns the value at the new index offset by n, wrapping around the total count of enum values.
Parameters
- value: The starting enum value.
Returns
- Return value 1: The enum value at the offset position, or the original value if the input value is not found.
Free Function: enum_prev_value
Canonical path: magic_enum::enum_prev_value
Declared in: include/magic_enum/magic_enum_utility.hpp
Signature
[[nodiscard]] constexpr auto enum_prev_value(E value, std::ptrdiff_t n = 1) noexcept -> detail::enable_if_t<E, optional<std::decay_t<E>>>;
Summary
Returns the enum value at an offset n from a given value, if it exists within the enum range.
Behavior
Calculates the index of the provided enum value and returns the enum value at the index shifted by n, provided the resulting index is within the valid range of 0 to count.
Parameters
- value: The enum value to start from.
Returns
- Return value 1: An optional containing the enum value at the offset index, or an empty optional if the index is out of bounds or the value is not found.
Free Function: enum_prev_value_circular
Canonical path: magic_enum::enum_prev_value_circular
Declared in: include/magic_enum/magic_enum_utility.hpp
Signature
[[nodiscard]] constexpr auto enum_prev_value_circular(E value, std::ptrdiff_t n = 1) noexcept -> detail::enable_if_t<E, std::decay_t<E>>;
Summary
Returns the enum value at a circular offset n from a given value.
Behavior
Calculates the index of the provided enum value and returns the enum value at the new index shifted by n, wrapping around the total count of enum values if the index exceeds the range.
Parameters
- value: The enum value to start from.
Returns
- Return value 1: The enum value at the calculated circular offset, or the original value if the index cannot be determined.
Free Function: enum_reflected
Canonical path: magic_enum::enum_reflected
Declared in: include/magic_enum/magic_enum.hpp
Signatures
Overload 1
[[nodiscard]] constexpr auto enum_reflected(E value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks if a specific enum value is reflected.
Behavior
Delegates to another enum_reflected overload by casting the enum value to its underlying type.
Parameters
- value: The enum value to check for reflection support.
Returns
- Return value 1: True if the enum value is reflected, false otherwise.
Overload 2
[[nodiscard]] constexpr auto enum_reflected(E value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks if an enum value is reflected using a specific subtype.
Behavior
Delegates the reflection check to an overload of enum_reflected using the decayed type of the provided value.
Parameters
- value: The enum value to check.
Returns
- Return value 1: True if the value is reflected, false otherwise.
Overload 3
[[nodiscard]] constexpr auto enum_reflected(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks if an underlying enum value is within the reflected range.
Behavior
Checks if the provided underlying value falls within the reflected range defined by the minimum and maximum reflected values for the enum type.
Parameters
- value: The underlying integer value of an enum to check.
Returns
- Return value 1: True if the value is within the reflected range, false if it is outside the range or if the enum is not reflected.
Free Function: enum_switch
Canonical path: magic_enum::enum_switch
Declared in: include/magic_enum/magic_enum_switch.hpp
Signatures
Overload 1
constexpr decltype(auto) enum_switch(F&& f, E value);
Summary
Invokes a function based on an enum value using a compile-time switch.
Behavior
Forwards the function object and value to another enum_switch overload that explicitly includes the enum type and subtype.
Parameters
- f: The function or callable to invoke.
- value: The enum value to switch on.
Returns
- Return value 1: The result of the invoked function.
Overload 2
constexpr decltype(auto) enum_switch(F&& f, E value);
Summary
Executes a switch-like operation on an enum value at compile time.
Behavior
Performs a compile-time switch on the provided enum value to invoke the function f. It requires the type to be an enum and to be reflected. Depending on configuration, it uses a hash-based switch or a standard constexpr switch.
Parameters
- f: The callable to be executed for the matching enum case.
- value: The enum value used to determine which case to execute.
Returns
- Return value 1: The result of the function call corresponding to the enum value.
Overload 3
constexpr decltype(auto) enum_switch(F&& f, E value, Result&& result);
Summary
Executes a switch on an enum value with a provided default result.
Behavior
Forwards the function, value, and default result to another enum_switch overload.
Parameters
- f: The callable to invoke.
- value: The enum value to switch on.
- result: The default result to return if no case matches.
Returns
- Return value 1: The result of the function call or the default result.
Overload 4
constexpr decltype(auto) enum_switch(F&& f, E value, Result&& result);
Summary
Performs a switch on an enum value with a fallback result.
Behavior
Executes a compile-time switch on the enum value. If the value is not found, it returns the provided default result.
Parameters
- f: The callable to execute for the matching enum value.
- value: The enum value to switch on.
- result: The result to return if the enum value does not match any reflected cases.
Returns
- Return value 1: The result of the function call or the default result.
Free Function: enum_type_name
Canonical path: magic_enum::enum_type_name
Declared in: include/magic_enum/magic_enum.hpp
Signature
[[nodiscard]] constexpr auto enum_type_name() noexcept -> detail::enable_if_t<E, string_view>;
Summary
Returns the name of the enum type.
Behavior
Retrieves the name of the enum type as a string view and asserts that the name is not empty.
Returns
- Return value 1: A string view containing the name of the enum type.
Free Function: enum_underlying
Canonical path: magic_enum::enum_underlying
Declared in: include/magic_enum/magic_enum.hpp
Signature
[[nodiscard]] constexpr auto enum_underlying(E value) noexcept -> detail::enable_if_t<E, underlying_type_t<E>>;
Summary
Converts an enum value to its underlying type.
Behavior
Performs a static cast of the enum value to its underlying integral type.
Parameters
- value: The enum value to convert.
Returns
- Return value 1: The underlying integral value of the enum.
Free Function: enum_value
Canonical path: magic_enum::enum_value
Declared in: include/magic_enum/magic_enum.hpp
Signatures
Overload 1
[[nodiscard]] constexpr auto enum_value() noexcept -> detail::enable_if_t<E, std::decay_t<E>>;
Summary
Returns the enum value at a specific compile-time index.
Behavior
Asserts that the enum is reflected and that the template index I is within the valid range of enum values before returning the value at that index.
Returns
- Return value 1: The enum value at the specified template index I.
Overload 2
[[nodiscard]] constexpr auto enum_value(std::size_t index) noexcept -> detail::enable_if_t<E, std::decay_t<E>>;
Summary
Returns the enum value at a specific runtime index.
Behavior
Retrieves the enum value at the specified index. For sparse enums, it accesses the values array directly. For non-sparse enums, it calculates the value based on the index and the minimum reflected value.
Parameters
- index: The zero-based index of the enum value to retrieve.
Returns
- Return value 1: The enum value at the given index.
Free Function: enum_values
Canonical path: magic_enum::enum_values
Declared in: include/magic_enum/magic_enum.hpp
Signature
[[nodiscard]] constexpr auto enum_values() noexcept -> detail::enable_if_t<E, detail::values_t<E, S>>;
Summary
Returns all reflected values of an enum type.
Behavior
Asserts that the enum type is reflected and returns a collection of all reflected enum values.
Returns
- Return value 1: A collection containing all reflected values of the enum.
Struct: is_scoped_enum
Canonical path: magic_enum::is_scoped_enum
Declared in: include/magic_enum/magic_enum.hpp
Signature
struct is_scoped_enum : detail::is_scoped_enum<T> {};
Summary
A type trait that identifies if a type is a scoped enum.
Struct: is_unscoped_enum
Canonical path: magic_enum::is_unscoped_enum
Declared in: include/magic_enum/magic_enum.hpp
Signature
struct is_unscoped_enum : detail::is_unscoped_enum<T> {};
Summary
A type trait that identifies if a type is an unscoped enum.
Struct: underlying_type
Canonical path: magic_enum::underlying_type
Declared in: include/magic_enum/magic_enum.hpp
Signature
struct underlying_type : detail::underlying_type<T> {};
Summary
A type trait that provides the underlying type of an enum.