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
Converts a string to an enum value of type E.
Behavior
Searches for an enum value whose name matches the provided string using a binary predicate. If MAGIC_ENUM_ENABLE_HASH is defined and the default predicate is used, it employs a constexpr switch; otherwise, it performs a linear search through reflected names.
Parameters
- value: The string representation of the enum value to search for.
Returns
- Return value 1: An optional containing the matched enum value, or an empty optional if no match is found.
Overload 2
[[nodiscard]] constexpr auto enum_cast(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, optional<std::decay_t<E>>>;
Summary
Converts an underlying integer value to an enum value of type E.
Behavior
Validates if the underlying value corresponds to a reflected enum member. For sparse or flag enums, it checks against reflected values (using a constexpr switch if hashing is enabled). For dense enums, it checks if the value is within the reflected range.
Parameters
- value: The underlying integer value to convert 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 if an enum value is valid.
Behavior
Checks if the provided enum value is valid by casting its underlying value and verifying the result.
Parameters
- value: The enum value to check.
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 if an enum value is valid for a specific subtype.
Behavior
Determines validity by casting the underlying representation of the enum value using the specified subtype S.
Parameters
- value: The enum value to check.
Returns
- Return value 1: True if the value is valid within the specified 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 if a string corresponds to a valid enum name.
Behavior
Attempts to cast the string to an enum value using the provided predicate and returns whether the cast succeeded.
Parameters
- value: The string name to check.
Returns
- Return value 1: True if the string matches a reflected enum name, false otherwise.
Overload 4
[[nodiscard]] constexpr auto enum_contains(underlying_type_t<E> value) noexcept -> detail::enable_if_t<E, bool>;
Summary
Checks if an underlying integer value is a valid enum member.
Behavior
Casts the underlying integer value to an enum and returns whether the resulting optional is populated.
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 members.
Behavior
Retrieves the count of reflected enum members for type E and subtype S.
Returns
- Return value 1: The number of entries in the enum.
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 the entries of the enum.
Behavior
Returns a collection of reflected enum entries for type E and subtype S, ensuring the enum is reflected via a static assertion.
Returns
- Return value 1: A collection of enum entries.
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
Converts a string of flags to an enum value.
Behavior
Parses a string containing pipe-separated flag names. It iterates through the string, matching each segment against reflected flag names using the provided predicate, and combines the results 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 value, or an empty optional if any segment is invalid or the result is zero.
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
Converts an underlying integer bitmask to a flag enum value.
Behavior
Validates a bitmask value. For sparse enums, it verifies that every set bit in the input corresponds to a reflected flag. For non-sparse enums, it checks if the value is within the range defined by the minimum and the bitwise OR of all reflected values.
Parameters
- value: The underlying integer bitmask to validate.
Returns
- Return value 1: An optional containing the 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 if a flag enum value is valid.
Behavior
Checks if the flag enum value is valid by attempting to cast its underlying representation.
Parameters
- value: The flag enum value to check.
Returns
- Return value 1: True if the value is a valid combination of reflected 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 if a string represents valid enum flags.
Behavior
Determines if the provided string can be successfully cast to a valid flag enum value.
Parameters
- value: The string of flags to check.
Returns
- Return value 1: True if the string represents 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 is a valid flag bitmask.
Behavior
Validates an underlying integer bitmask by attempting to cast it to the flag enum type.
Parameters
- value: The underlying integer bitmask to check.
Returns
- Return value 1: True if the bitmask is a valid combination of reflected flags, 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
Obtains a string representation of the set flags in an enum value.
Behavior
Iterates through the reflected flags of an enum type and appends the names of all set bits to a string, separated by a specified character. It returns an empty string if any set bit lacks a reflected name or if the final calculated value does not match the input.
Parameters
- value: The enum value whose flag names are to be retrieved.
Returns
- Return value 1: A string containing the names of the set flags separated by the separator, 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 set within an enum value.
Behavior
Checks if all bits set in the second enum value are also set in the first enum value, provided the second value is non-zero.
Parameters
- flags: The enum value containing the set of flags to check against.
- flag: The specific flag or set of flags to look for within the first parameter.
Returns
- Return value 1: True if the second value is non-zero and all its bits are present in the first value; otherwise false.
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 test.
- rhs: The right-hand side enum value for the bitwise test.
Returns
- Return value 1: True if any bits are set in both 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
Invokes a function for every reflected value of an enum.
Behavior
Iterates over all reflected values of an enum type and invokes the provided callable for each value. It uses a static assertion to ensure the callable is invocable with every enum value.
Parameters
- f: The callable object to be invoked for each enum value.
Returns
- Return value 1: The result of the internal for_each execution.
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 representation.
Behavior
Combines multiple enum values into a single fused value. It requires at least two enum values and ensures the combined bit-width does not exceed the size of uintmax_t. Depending on configuration, it uses either a standard or typesafe fusion implementation.
Returns
- Return value 1: The fused value resulting from the combination of the input enum values.
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
Returns the index of a compile-time enum value.
Behavior
Retrieves the zero-based index of a compile-time enum constant. It asserts at compile-time that the enum is reflected and that the specific value has a valid index.
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 a runtime enum value.
Behavior
Calculates the index of an enum value. For sparse or flag enums, it performs a lookup (optionally using a hash-based switch). For dense enums, it calculates the index based on the difference from the minimum reflected value.
Parameters
- value: The enum value for which to find the index.
Returns
- Return value 1: An optional containing the index if the value is valid and reflected, 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 using a specific enum 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 enum 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
enum_integer is a constexpr noexcept function template that converts an enum value to its underlying integer type.
Behavior
The function performs a static cast of the input value to its underlying type.
Parameters
- value: The parameter value is of template type E.
Returns
- Return value 1: The function returns the value cast to the underlying type of E, specified as underlying_type_t<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
Returns the name of a compile-time enum value.
Behavior
Retrieves the name of a compile-time enum constant. It asserts at compile-time that the name is not empty.
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 a runtime enum value.
Behavior
Looks up the name of a runtime enum value by first finding its index. If the value is not reflected or invalid, it returns an empty string.
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 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 using a specific enum subtype.
Behavior
Delegates the name lookup to the primary enum_name implementation for the specified enum type and subtype.
Parameters
- value: The enum value to look up.
Returns
- Return value 1: A string_view containing the name of the enum value.
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
Returns a list of all reflected enum names.
Behavior
Returns a collection containing the names of all reflected values for the specified enum type and subtype.
Returns
- Return value 1: A detail::names_t object 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
Returns the enum value at a specific offset from a given value.
Behavior
Finds the index of the provided enum value and adds the offset n. If the resulting index is within the valid range of reflected values, it returns the corresponding enum value.
Parameters
- value: The starting enum value.
Returns
- Return value 1: An optional containing the enum value at the offset if it exists, otherwise an empty optional.
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
Returns the enum value at a circular offset from a given value.
Behavior
Calculates the index of the current value, offsets it by n, and wraps the result around the total count of reflected values using modulo arithmetic. If the input value is not reflected, it triggers an assertion and returns the original value.
Parameters
- value: The starting enum value.
Returns
- Return value 1: The enum value at the calculated circular offset.
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
Obtains the previous enum value.
Behavior
Calculates the index of the previous enum value by subtracting n from the current index, returning an empty optional if the resulting index is out of bounds.
Parameters
- value: The starting enum value.
Returns
- Return value 1: Returns an optional containing the previous enum value, or an empty optional if the index is invalid.
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
Obtains the previous enum value with circular wrapping.
Behavior
Calculates the index of the previous enum value relative to the provided value, wrapping around to the end of the enum range if the calculation goes below zero.
Parameters
- value: The enum value from which to calculate the previous value.
Returns
- Return value 1: Returns the previous enum value in a circular manner, or the original value if the input value is not found.
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 an enum value is reflected.
Behavior
Checks if the provided enum value is reflected by casting it to its underlying type and calling the corresponding overload.
Parameters
- value: The enum value to check for reflection.
Returns
- Return value 1: Returns 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
Invokes the enum_reflected overload for the decayed enum type and specified subtype.
Parameters
- value: The enum value to check.
Returns
- Return value 1: Returns the result of the reflection check as a boolean.
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
Determines if the underlying value falls within the reflected minimum and maximum range for the specified enum and subtype.
Parameters
- value: The underlying integer value of an enum to check.
Returns
- Return value 1: Returns true if the value is within the reflected range, false otherwise.
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
Dispatches a function call based on an enum value.
Behavior
Forwards the function object and enum value to another enum_switch overload specifying the result type and subtype.
Parameters
- f: The function object to be called.
- value: The enum value used to determine which case to switch to.
Returns
- Return value 1: Returns the result of the function call associated with the enum value.
Overload 2
constexpr decltype(auto) enum_switch(F&& f, E value);
Summary
Performs a switch-like dispatch on an enum value at compile time.
Behavior
Uses a compile-time switch mechanism to invoke the provided function with the constant expression value corresponding to the runtime enum value.
Parameters
- f: The callable to invoke.
- value: The runtime enum value.
Returns
- Return value 1: Returns the result of the invoked function.
Overload 3
constexpr decltype(auto) enum_switch(F&& f, E value, Result&& result);
Summary
Dispatches a function call based on an enum value with a default result.
Behavior
Forwards the function, value, and default result to the internal enum_switch implementation.
Parameters
- f: The function to execute.
- value: The enum value to switch on.
- result: The default result to return if the enum value is not handled.
Returns
- Return value 1: Returns the result of the function or the provided 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 that returns a provided default result via a lambda if the enum value is not matched.
Parameters
- f: The function to call for the matched enum value.
- value: The enum value.
- result: The result to return if no match is found.
Returns
- Return value 1: Returns the function result 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
Obtains the name of the enum type.
Behavior
Retrieves the name of the enum type as a string view, asserting that the name is not empty.
Returns
- Return value 1: Returns 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
Obtains the underlying value of an enum.
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: Returns the underlying integer 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
Obtains an enum value by its compile-time index.
Behavior
Validates that the enum is reflected and the index is within range before returning the value at the specified template index.
Returns
- Return value 1: Returns the enum value at the specified compile-time index.
Overload 2
[[nodiscard]] constexpr auto enum_value(std::size_t index) noexcept -> detail::enable_if_t<E, std::decay_t<E>>;
Summary
Obtains an enum value by its runtime index.
Behavior
Retrieves the enum value at the given index, handling both sparse and non-sparse enum layouts.
Parameters
- index: The zero-based index of the enum value.
Returns
- Return value 1: Returns the enum value corresponding to the 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
Obtains all values of an enum.
Behavior
Ensures the enum is reflected and returns a collection of all its values.
Returns
- Return value 1: Returns a constant array-like object containing all 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 trait that determines if a type is a scoped enumeration.
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 trait that determines if a type is an unscoped enumeration.
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 trait that provides the underlying type of an enumeration.