mirror/magic_enum
1
0
Fork 0
mirror of https://github.com/Neargye/magic_enum.git synced 2026-01-10 23:44:29 +00:00
Code Activity

update doc

Browse source
This commit is contained in:
Neargye 2020-01-25 22:55:18 +05:00
parent a576c077be
commit 06a8669d49
3 changed files with 97 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -62,6 +62,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Enum value to string * Enum value to string
```cpp ```cpp
Color color = Color::RED; Color color = Color::RED;
auto color_name = magic_enum::enum_name(color); auto color_name = magic_enum::enum_name(color);
@ -69,6 +70,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* String to enum value * String to enum value
```cpp ```cpp
std::string color_name{"GREEN"}; std::string color_name{"GREEN"};
auto color = magic_enum::enum_cast<Color>(color_name); auto color = magic_enum::enum_cast<Color>(color_name);
@ -78,6 +80,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Integer to enum value * Integer to enum value
```cpp ```cpp
int color_integer = 2; int color_integer = 2;
auto color = magic_enum::enum_cast<Color>(color_integer); auto color = magic_enum::enum_cast<Color>(color_integer);
@ -87,6 +90,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Indexed access to enum value * Indexed access to enum value
```cpp ```cpp
int i = 1; int i = 1;
Color color = magic_enum::enum_value<Color>(i); Color color = magic_enum::enum_value<Color>(i);
@ -94,6 +98,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Enum value sequence * Enum value sequence
```cpp ```cpp
constexpr auto colors = magic_enum::enum_values<Color>(); constexpr auto colors = magic_enum::enum_values<Color>();
// colors -> {Color::RED, Color::BLUE, Color::GREEN} // colors -> {Color::RED, Color::BLUE, Color::GREEN}
@ -101,12 +106,14 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Number of enum elements * Number of enum elements
```cpp ```cpp
constexpr std::size_t color_count = magic_enum::enum_count<Color>(); constexpr std::size_t color_count = magic_enum::enum_count<Color>();
// color_count -> 3 // color_count -> 3
``` ```
* Enum value to integer * Enum value to integer
```cpp ```cpp
Color color = Color::RED; Color color = Color::RED;
auto color_integer = magic_enum::enum_integer(color); auto color_integer = magic_enum::enum_integer(color);
@ -114,6 +121,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Enum names sequence * Enum names sequence
```cpp ```cpp
constexpr auto color_names = magic_enum::enum_names<Color>(); constexpr auto color_names = magic_enum::enum_names<Color>();
// color_names -> {"RED", "BLUE", "GREEN"} // color_names -> {"RED", "BLUE", "GREEN"}
@ -121,6 +129,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Enum entries sequence * Enum entries sequence
```cpp ```cpp
constexpr auto color_entries = magic_enum::enum_entries<Color>(); constexpr auto color_entries = magic_enum::enum_entries<Color>();
// color_entries -> {{Color::RED, "RED"}, {Color::BLUE, "BLUE"}, {Color::GREEN, "GREEN"}} // color_entries -> {{Color::RED, "RED"}, {Color::BLUE, "BLUE"}, {Color::GREEN, "GREEN"}}
@ -129,6 +138,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Ostream operator for enum * Ostream operator for enum
```cpp ```cpp
using namespace magic_enum::ostream_operators; // out-of-the-box ostream operators for enums. using namespace magic_enum::ostream_operators; // out-of-the-box ostream operators for enums.
Color color = Color::BLUE; Color color = Color::BLUE;
@ -136,6 +146,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Bitwise operator for enum * Bitwise operator for enum
```cpp ```cpp
enum class Flags { A = 1 << 0, B = 1 << 1, C = 1 << 2, D = 1 << 3 }; enum class Flags { A = 1 << 0, B = 1 << 1, C = 1 << 2, D = 1 << 3 };
using namespace magic_enum::bitwise_operators; // out-of-the-box bitwise operators for enums. using namespace magic_enum::bitwise_operators; // out-of-the-box bitwise operators for enums.
@ -144,6 +155,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Checks whether type is an [Unscoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Unscoped_enumeration). * Checks whether type is an [Unscoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Unscoped_enumeration).
```cpp ```cpp
enum color { red, green, blue }; enum color { red, green, blue };
enum class direction { left, right }; enum class direction { left, right };
@ -157,6 +169,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
``` ```
* Checks whether type is an [Scoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Scoped_enumerations). * Checks whether type is an [Scoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Scoped_enumerations).
```cpp ```cpp
enum color { red, green, blue }; enum color { red, green, blue };
enum class direction { left, right }; enum class direction { left, right };
@ -171,12 +184,19 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 };
* Static storage enum variable to string * Static storage enum variable to string
This version is much lighter on the compile times and is not restricted to the enum_range [limitation](doc/limitations.md). This version is much lighter on the compile times and is not restricted to the enum_range [limitation](doc/limitations.md).
```cpp ```cpp
constexpr Color color = Color::BLUE; constexpr Color color = Color::BLUE;
constexpr auto color_name = magic_enum::enum_name<color>(); constexpr auto color_name = magic_enum::enum_name<color>();
// color_name -> "BLUE" // color_name -> "BLUE"
``` ```
## Remarks
* `magic_enum` does not pretend to be a silver bullet for reflection for enums, it was originally designed for small enum.
* Before use, read the [limitations](limitations.md) of functionality.
## Integration ## Integration
You should add the required file [magic_enum.hpp](include/magic_enum.hpp). You should add the required file [magic_enum.hpp](include/magic_enum.hpp).

59
doc/limitations.md
View file

@ -8,29 +8,48 @@
* Enum value must be in range `[MAGIC_ENUM_RANGE_MIN, MAGIC_ENUM_RANGE_MAX]`. By default `MAGIC_ENUM_RANGE_MIN = -128`, `MAGIC_ENUM_RANGE_MAX = 128`. * Enum value must be in range `[MAGIC_ENUM_RANGE_MIN, MAGIC_ENUM_RANGE_MAX]`. By default `MAGIC_ENUM_RANGE_MIN = -128`, `MAGIC_ENUM_RANGE_MAX = 128`.
If need another range for all enum types by default, redefine the macro `MAGIC_ENUM_RANGE_MIN` and `MAGIC_ENUM_RANGE_MAX`. * `MAGIC_ENUM_RANGE_MAX` must be greater than `0` and must be less than `INT16_MAX`.
```cpp
#define MAGIC_ENUM_RANGE_MIN 0 * `MAGIC_ENUM_RANGE_MIN` must be less or equals than `0` and must be greater than `INT16_MIN`.
#define MAGIC_ENUM_RANGE_MAX 256
#include <magic_enum.hpp> * If need another range for all enum types by default, redefine the macro `MAGIC_ENUM_RANGE_MIN` and `MAGIC_ENUM_RANGE_MAX`.
```cpp
#define MAGIC_ENUM_RANGE_MIN 0
#define MAGIC_ENUM_RANGE_MAX 256
#include <magic_enum.hpp>
```
If need another range for specific enum type, add specialization `enum_range` for necessary enum type.
```cpp
#include <magic_enum.hpp>
enum number { one = 100, two = 200, three = 300 };
namespace magic_enum {
template <>
struct enum_range<number> {
static constexpr int min = 100; // Must be greater than `INT16_MIN`.
static constexpr int max = 300; // Must be less than `INT16_MAX`.
};
}
```
* If you hit a message like this:
```text
[...]
note: constexpr evaluation hit maximum step limit; possible infinite loop?
``` ```
If need another range for specific enum type, add specialization `enum_range` for necessary enum type. Change the limit for the number of constexpr evaluated:
```cpp * MSVC `/constexpr:depthN`, `/constexpr:stepsN` <https://docs.microsoft.com/en-us/cpp/build/reference/constexpr-control-constexpr-evaluation>
#include <magic_enum.hpp> * Clang `-fconstexpr-depth=N`, `-fconstexpr-steps=N` <https://clang.llvm.org/docs/UsersManual.html#controlling-implementation-limits>
* GCC `-fconstexpr-depth=n`, `-fconstexpr-loop-limit=n`, `-fconstexpr-ops-limit=n` <https://gcc.gnu.org/onlinedocs/gcc-9.2.0/gcc/C_002b_002b-Dialect-Options.html>
enum number { one = 100, two = 200, three = 300 };
namespace magic_enum {
template <>
struct enum_range<number> {
static constexpr int min = 100;
static constexpr int max = 300;
};
}
```
* `magic_enum` obtains the first defined value enums, and won't work if value are aliased. * `magic_enum` obtains the first defined value enums, and won't work if value are aliased.
```cpp ```cpp
enum ShapeKind { enum ShapeKind {
ConvexBegin = 0, ConvexBegin = 0,
@ -44,7 +63,9 @@
// magic_enum::enum_cast<ShapeKind>("Box") -> std::nullopt // magic_enum::enum_cast<ShapeKind>("Box") -> std::nullopt
// magic_enum::enum_name(ShapeKind::Box) -> "ConvexBegin" // magic_enum::enum_name(ShapeKind::Box) -> "ConvexBegin"
``` ```
Work around the issue: Work around the issue:
```cpp ```cpp
enum ShapeKind { enum ShapeKind {
// Convex shapes, see ConvexBegin and ConvexEnd below. // Convex shapes, see ConvexBegin and ConvexEnd below.

43
doc/reference.md
View file

@ -15,7 +15,7 @@
* [`ostream_operators` ostream operators for enums.](#ostream_operators) * [`ostream_operators` ostream operators for enums.](#ostream_operators)
* [`bitwise_operators` bitwise operators for enums.](#bitwise_operators) * [`bitwise_operators` bitwise operators for enums.](#bitwise_operators)
# Synopsis ## Synopsis
* Before use, read the [limitations](limitations.md) of functionality. * Before use, read the [limitations](limitations.md) of functionality.
@ -23,6 +23,7 @@
If magic_enum used on unsupported compiler, occurs the compilation error. To suppress error define macro `MAGIC_ENUM_NO_CHECK_SUPPORT`. If magic_enum used on unsupported compiler, occurs the compilation error. To suppress error define macro `MAGIC_ENUM_NO_CHECK_SUPPORT`.
## `enum_cast` ## `enum_cast`
```cpp ```cpp
template <typename E> template <typename E>
constexpr optional<E> enum_cast(string_view value) noexcept; constexpr optional<E> enum_cast(string_view value) noexcept;
@ -38,7 +39,9 @@ constexpr optional<E> enum_cast(underlying_type_t<E> value) noexcept;
* If argument does not enum value, returns empty `std::optional`. * If argument does not enum value, returns empty `std::optional`.
* Examples * Examples
* String to enum value.
* String to enum value.
```cpp ```cpp
std::string color_name{"GREEN"}; std::string color_name{"GREEN"};
auto color = magic_enum::enum_cast<Color>(color_name); auto color = magic_enum::enum_cast<Color>(color_name);
@ -46,7 +49,9 @@ constexpr optional<E> enum_cast(underlying_type_t<E> value) noexcept;
// color.value() -> Color::GREEN // color.value() -> Color::GREEN
} }
``` ```
* Integer to enum value.
* Integer to enum value.
```cpp ```cpp
int color_integer = 2; int color_integer = 2;
auto color = magic_enum::enum_cast<Color>(color_integer); auto color = magic_enum::enum_cast<Color>(color_integer);
@ -56,6 +61,7 @@ constexpr optional<E> enum_cast(underlying_type_t<E> value) noexcept;
``` ```
## `enum_value` ## `enum_value`
```cpp ```cpp
template <typename E> template <typename E>
constexpr E enum_value(size_t index) noexcept; constexpr E enum_value(size_t index) noexcept;
@ -66,6 +72,7 @@ constexpr E enum_value(size_t index) noexcept;
* No bounds checking is performed: the behavior is undefined if `index >= number of enum values`. * No bounds checking is performed: the behavior is undefined if `index >= number of enum values`.
* Examples * Examples
```cpp ```cpp
int i = 1; int i = 1;
Color color = magic_enum::enum_value<Color>(i); Color color = magic_enum::enum_value<Color>(i);
@ -73,6 +80,7 @@ constexpr E enum_value(size_t index) noexcept;
```` ````
## `enum_values` ## `enum_values`
```cpp ```cpp
template <typename E> template <typename E>
constexpr array<E, N> enum_values() noexcept; constexpr array<E, N> enum_values() noexcept;
@ -81,6 +89,7 @@ constexpr array<E, N> enum_values() noexcept;
* Returns `std::array<E, N>` with all enum value where `N = number of enum values`, sorted by enum value. * Returns `std::array<E, N>` with all enum value where `N = number of enum values`, sorted by enum value.
* Examples * Examples
```cpp ```cpp
constexpr auto colors = magic_enum::enum_values<Color>(); constexpr auto colors = magic_enum::enum_values<Color>();
// colors -> {Color::RED, Color::BLUE, Color::GREEN} // colors -> {Color::RED, Color::BLUE, Color::GREEN}
@ -88,6 +97,7 @@ constexpr array<E, N> enum_values() noexcept;
``` ```
## `enum_count` ## `enum_count`
```cpp ```cpp
template <typename E> template <typename E>
constexpr size_t enum_count() noexcept; constexpr size_t enum_count() noexcept;
@ -96,12 +106,14 @@ constexpr size_t enum_count() noexcept;
* Returns number of enum values. * Returns number of enum values.
* Examples * Examples
```cpp ```cpp
constexpr std::size_t color_count = magic_enum::enum_count<Color>(); constexpr std::size_t color_count = magic_enum::enum_count<Color>();
// color_count -> 3 // color_count -> 3
``` ```
## `enum_integer` ## `enum_integer`
```cpp ```cpp
template <typename E> template <typename E>
constexpr underlying_type_t<E> enum_integer(E value) noexcept; constexpr underlying_type_t<E> enum_integer(E value) noexcept;
@ -110,6 +122,7 @@ constexpr underlying_type_t<E> enum_integer(E value) noexcept;
* Returns integer value from enum value. * Returns integer value from enum value.
* Examples * Examples
```cpp ```cpp
Color color = Color::RED; Color color = Color::RED;
auto color_integer = magic_enum::enum_integer(color); auto color_integer = magic_enum::enum_integer(color);
@ -117,6 +130,7 @@ constexpr underlying_type_t<E> enum_integer(E value) noexcept;
``` ```
## `enum_name` ## `enum_name`
```cpp ```cpp
template <typename E> template <typename E>
constexpr string_view enum_name(E value) noexcept; constexpr string_view enum_name(E value) noexcept;
@ -128,14 +142,18 @@ constexpr string_view enum_name() noexcept;
* Returns `std::string_view`. If enum value does not have name, returns empty string. * Returns `std::string_view`. If enum value does not have name, returns empty string.
* Examples * Examples
* Enum value to string.
* Enum value to string.
```cpp ```cpp
Color color = Color::RED; Color color = Color::RED;
auto color_name = magic_enum::enum_name(color); auto color_name = magic_enum::enum_name(color);
// color_name -> "RED" // color_name -> "RED"
``` ```
* Static storage enum variable to string.
* Static storage enum variable to string.
This version is much lighter on the compile times and is not restricted to the enum_range [limitation](doc/limitations.md). This version is much lighter on the compile times and is not restricted to the enum_range [limitation](doc/limitations.md).
```cpp ```cpp
constexpr Color color = Color::BLUE; constexpr Color color = Color::BLUE;
constexpr auto color_name = magic_enum::enum_name<color>(); constexpr auto color_name = magic_enum::enum_name<color>();
@ -144,8 +162,8 @@ constexpr string_view enum_name() noexcept;
* `magic_enum::enum_name<value>()` is much lighter on the compile times and is not restricted to the enum_range [limitation](limitation.md). * `magic_enum::enum_name<value>()` is much lighter on the compile times and is not restricted to the enum_range [limitation](limitation.md).
## `enum_names` ## `enum_names`
```cpp ```cpp
template <typename E> template <typename E>
constexpr array<string_view, N> enum_names() noexcept; constexpr array<string_view, N> enum_names() noexcept;
@ -154,6 +172,7 @@ constexpr array<string_view, N> enum_names() noexcept;
* Returns `std::array<std::string_view, N>` with all string enum name where `N = number of enum values`, sorted by enum value. * Returns `std::array<std::string_view, N>` with all string enum name where `N = number of enum values`, sorted by enum value.
* Examples * Examples
```cpp ```cpp
constexpr auto color_names = magic_enum::enum_names<Color>(); constexpr auto color_names = magic_enum::enum_names<Color>();
// color_names -> {"RED", "BLUE", "GREEN"} // color_names -> {"RED", "BLUE", "GREEN"}
@ -161,6 +180,7 @@ constexpr array<string_view, N> enum_names() noexcept;
``` ```
## `enum_entries` ## `enum_entries`
```cpp ```cpp
template <typename E> template <typename E>
constexpr array<pair<E, string_view>, N> enum_entries() noexcept; constexpr array<pair<E, string_view>, N> enum_entries() noexcept;
@ -169,6 +189,7 @@ constexpr array<pair<E, string_view>, N> enum_entries() noexcept;
* Returns `std::array<std::pair<E, std::string_view>, N>` with all `std::pair` (value enum, string enum name) where `N = number of enum values`, sorted by enum value. * Returns `std::array<std::pair<E, std::string_view>, N>` with all `std::pair` (value enum, string enum name) where `N = number of enum values`, sorted by enum value.
* Examples * Examples
```cpp ```cpp
constexpr auto color_entries = magic_enum::enum_entries<Color>(); constexpr auto color_entries = magic_enum::enum_entries<Color>();
// color_entries -> {{Color::RED, "RED"}, {Color::BLUE, "BLUE"}, {Color::GREEN, "GREEN"}} // color_entries -> {{Color::RED, "RED"}, {Color::BLUE, "BLUE"}, {Color::GREEN, "GREEN"}}
@ -177,6 +198,7 @@ constexpr array<pair<E, string_view>, N> enum_entries() noexcept;
``` ```
## `is_unscoped_enum` ## `is_unscoped_enum`
```cpp ```cpp
template <typename T> template <typename T>
struct is_unscoped_enum; struct is_unscoped_enum;
@ -190,6 +212,7 @@ inline constexpr bool is_unscoped_enum_v = is_unscoped_enum<T>::value;
* Provides the member constant value which is equal to true, if T is an [Unscoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Unscoped_enumeration) type. Otherwise, value is equal to false. * Provides the member constant value which is equal to true, if T is an [Unscoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Unscoped_enumeration) type. Otherwise, value is equal to false.
* Examples * Examples
```cpp ```cpp
magic_enum::is_unscoped_enum<color>::value -> true magic_enum::is_unscoped_enum<color>::value -> true
magic_enum::is_unscoped_enum<Direction>::value -> false magic_enum::is_unscoped_enum<Direction>::value -> false
@ -199,6 +222,7 @@ inline constexpr bool is_unscoped_enum_v = is_unscoped_enum<T>::value;
``` ```
## `is_scoped_enum` ## `is_scoped_enum`
```cpp ```cpp
template <typename T> template <typename T>
struct is_scoped_enum; struct is_scoped_enum;
@ -212,6 +236,7 @@ inline constexpr bool is_scoped_enum_v = is_scoped_enum<T>::value;
* Provides the member constant value which is equal to true, if T is an [Scoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Scoped_enumerations) type. Otherwise, value is equal to false. * Provides the member constant value which is equal to true, if T is an [Scoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Scoped_enumerations) type. Otherwise, value is equal to false.
* Examples * Examples
```cpp ```cpp
magic_enum::is_scoped_enum<color>::value -> false magic_enum::is_scoped_enum<color>::value -> false
magic_enum::is_scoped_enum<Direction>::value -> true magic_enum::is_scoped_enum<Direction>::value -> true
@ -235,6 +260,7 @@ using underlying_type_t = typename underlying_type<T>::type;
* If T is a complete enumeration type, provides a member typedef type that names the underlying type of T. Otherwise, if T is not an enumeration type, there is no member type. Otherwise (T is an incomplete enumeration type), the program is ill-formed. * If T is a complete enumeration type, provides a member typedef type that names the underlying type of T. Otherwise, if T is not an enumeration type, there is no member type. Otherwise (T is an incomplete enumeration type), the program is ill-formed.
* Examples * Examples
```cpp ```cpp
magic_enum::underlying_type<color>::type -> int magic_enum::underlying_type<color>::type -> int
@ -243,6 +269,7 @@ using underlying_type_t = typename underlying_type<T>::type;
``` ```
## `ostream_operators` ## `ostream_operators`
```cpp ```cpp
template <typename Char, typename Traits, typename E> template <typename Char, typename Traits, typename E>
basic_ostream<Char, Traits>& operator<<(basic_ostream<Char, Traits>& os, E value); basic_ostream<Char, Traits>& operator<<(basic_ostream<Char, Traits>& os, E value);
@ -251,9 +278,11 @@ template <typename Char, typename Traits, typename E>
basic_ostream<Char, Traits>& operator<<(basic_ostream<Char, Traits>& os, optional<E> value); basic_ostream<Char, Traits>& operator<<(basic_ostream<Char, Traits>& os, optional<E> value);
``` ```
* Out-of-the-box ostream operators for all enums. * Out-of-the-box ostream operators for all enums.
* Examples * Examples
```cpp ```cpp
using namespace magic_enum::ostream_operators; // out-of-the-box ostream operators for enums. using namespace magic_enum::ostream_operators; // out-of-the-box ostream operators for enums.
Color color = Color::BLUE; Color color = Color::BLUE;
@ -261,6 +290,7 @@ basic_ostream<Char, Traits>& operator<<(basic_ostream<Char, Traits>& os, optiona
``` ```
## `bitwise_operators` ## `bitwise_operators`
```cpp ```cpp
template <typename E> template <typename E>
constexpr E operator~(E rhs) noexcept; constexpr E operator~(E rhs) noexcept;
@ -287,6 +317,7 @@ constexpr E& operator^=(E& lhs, E rhs) noexcept;
* Out-of-the-box bitwise operators for all enums. * Out-of-the-box bitwise operators for all enums.
* Examples * Examples
```cpp ```cpp
enum class Flags { A = 1 << 0, B = 1 << 1, C = 1 << 2, D = 1 << 3 }; enum class Flags { A = 1 << 0, B = 1 << 1, C = 1 << 2, D = 1 << 3 };
using namespace magic_enum::bitwise_operators; // out-of-the-box bitwise operators for enums. using namespace magic_enum::bitwise_operators; // out-of-the-box bitwise operators for enums.