Skip to main content

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

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.