From cd73e2b974c8f98a6abd5fe6a664f17fb9806e05 Mon Sep 17 00:00:00 2001 From: neargye Date: Thu, 3 Oct 2019 19:40:42 +0500 Subject: [PATCH] add doc --- README.md | 91 ++------------ doc/limitations.md | 70 +++++++++++ doc/reference.md | 294 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 373 insertions(+), 82 deletions(-) create mode 100644 doc/limitations.md create mode 100644 doc/reference.md diff --git a/README.md b/README.md index c859e74..f814bc7 100644 --- a/README.md +++ b/README.md @@ -35,8 +35,14 @@ Header-only C++17 library provides static reflection for enums, work with any en * `is_unscoped_enum` checks whether type is an [Unscoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Unscoped_enumeration). * `is_scoped_enum` checks whether type is an [Scoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Scoped_enumerations). * `underlying_type` improved UB-free "SFINAE-friendly" [std::underlying_type](https://en.cppreference.com/w/cpp/types/underlying_type). -* `using namespace magic_enum::ostream_operators;` ostream operators for enums. -* `using namespace magic_enum::bitwise_operators;` bitwise operators for enums. +* `ostream_operators` ostream operators for enums. +* `bitwise_operators` bitwise operators for enums. + +## Documentation + +* [Reference](doc/reference.md) +* [Limitations](doc/limitations.md) +* [Integration](#Integration) ## Features @@ -122,7 +128,7 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 }; // color_entries[0].second -> "RED" ``` -* Stream operator for enum +* Ostream operator for enum ```cpp using namespace magic_enum::ostream_operators; // out-of-the-box ostream operators for enums. Color color = Color::BLUE; @@ -171,85 +177,6 @@ enum Color { RED = 2, BLUE = 4, GREEN = 8 }; // color_name -> "BLUE" ``` -## Remarks - -* `magic_enum::enum_cast(value)` returns `std::optional`, using `has_value()` to check contains enum value and `value()` to get the enum value. - -* `magic_enum::enum_value(index)` no bounds checking is performed: the behavior is undefined if `index >= number of enum values`. - -* `magic_enum::enum_values()` returns `std::array` with all enum value where `N = number of enum values`, sorted by enum value. - -* `magic_enum::enum_name(value)` returns `std::string_view`. If enum value does not have name, returns empty string. - -* `magic_enum::enum_name()` is much lighter on the compile times and is not restricted to the enum_range limitation. - -* `magic_enum::enum_names()` returns `std::array` with all string enum name where `N = number of enum values`, sorted by enum value. - -* `magic_enum::enum_entries()` returns `std::array, N>` with all std::pair (value enum, string enum name) where `N = number of enum values`, sorted by enum value. - -* 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`. - ```cpp - #define MAGIC_ENUM_RANGE_MIN 0 - #define MAGIC_ENUM_RANGE_MAX 256 - #include - ``` - - If need another range for specific enum type, add specialization `enum_range` for necessary enum type. - ```cpp - #include - - enum number { one = 100, two = 200, three = 300 }; - - namespace magic_enum { - template <> - struct enum_range { - 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. - ```cpp - enum ShapeKind { - ConvexBegin = 0, - Box = 0, // Won't work. - Sphere = 1, - ConvexEnd = 2, - Donut = 2, // Won't work too. - Banana = 3, - COUNT = 4, - }; - // magic_enum::enum_cast("Box") -> std::nullopt - // magic_enum::enum_name(ShapeKind::Box) -> "ConvexBegin" - ``` - Work around the issue: - ```cpp - enum ShapeKind { - // Convex shapes, see ConvexBegin and ConvexEnd below. - Box = 0, - Sphere = 1, - - // Non-convex shapes. - Donut = 2, - Banana = 3, - - COUNT = Banana + 1, - - // Non-reflected aliases. - ConvexBegin = Box, - ConvexEnd = Sphere + 1, - }; - // magic_enum::enum_cast("Box") -> ShapeKind::Box - // magic_enum::enum_name(ShapeKind::Box) -> "Box" - - // Non-reflected aliases. - // magic_enum::enum_cast("ConvexBegin") -> std::nullopt - // magic_enum::enum_name(ShapeKind::ConvexBegin) -> "Box" - ``` - ## Integration You should add the required file [magic_enum.hpp](include/magic_enum.hpp). diff --git a/doc/limitations.md b/doc/limitations.md new file mode 100644 index 0000000..cbd8b73 --- /dev/null +++ b/doc/limitations.md @@ -0,0 +1,70 @@ +# Limitations + +* To check is magic_enum supported compiler use macro `MAGIC_ENUM_SUPPORTED` or constexpr constant `magic_enum::is_magic_enum_supported`. + +* This library uses a compiler-specific hack (based on `__PRETTY_FUNCTION__` / `__FUNCSIG__`), which works on Clang >= 5, MSVC >= 15.3 and GCC >= 9. + +* Enum can't reflect if the enum is a forward declaration. + +* 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`. + ```cpp + #define MAGIC_ENUM_RANGE_MIN 0 + #define MAGIC_ENUM_RANGE_MAX 256 + #include + ``` + + If need another range for specific enum type, add specialization `enum_range` for necessary enum type. + ```cpp + #include + + enum number { one = 100, two = 200, three = 300 }; + + namespace magic_enum { + template <> + struct enum_range { + 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. + ```cpp + enum ShapeKind { + ConvexBegin = 0, + Box = 0, // Won't work. + Sphere = 1, + ConvexEnd = 2, + Donut = 2, // Won't work too. + Banana = 3, + COUNT = 4, + }; + // magic_enum::enum_cast("Box") -> std::nullopt + // magic_enum::enum_name(ShapeKind::Box) -> "ConvexBegin" + ``` + Work around the issue: + ```cpp + enum ShapeKind { + // Convex shapes, see ConvexBegin and ConvexEnd below. + Box = 0, + Sphere = 1, + + // Non-convex shapes. + Donut = 2, + Banana = 3, + + COUNT = Banana + 1, + + // Non-reflected aliases. + ConvexBegin = Box, + ConvexEnd = Sphere + 1, + }; + // magic_enum::enum_cast("Box") -> ShapeKind::Box + // magic_enum::enum_name(ShapeKind::Box) -> "Box" + + // Non-reflected aliases. + // magic_enum::enum_cast("ConvexBegin") -> std::nullopt + // magic_enum::enum_name(ShapeKind::ConvexBegin) -> "Box" + ``` diff --git a/doc/reference.md b/doc/reference.md new file mode 100644 index 0000000..cf37f0e --- /dev/null +++ b/doc/reference.md @@ -0,0 +1,294 @@ +# Reference + +* [`enum_cast` obtains enum value from string or integer.](#enum_cast) +* [`enum_value` returns enum value at specified index.](#enum_value) +* [`enum_values` obtains enum value sequence.](#enum_values) +* [`enum_count` returns number of enum values.](#enum_count) +* [`enum_integer` obtains integer value from enum value.](#enum_integer) +* [`enum_name` returns string name from enum value.](#enum_name) +* [`enum_names` obtains string enum name sequence.](#enum_names) +* [`enum_entries` obtains pair (value enum, string enum name) sequence.](#enum_entries) +* [`enum_index` obtains index in enum value sequence from enum value.](#enum_index) +* [`is_unscoped_enum` checks whether type is an Unscoped enumeration.](#is_unscoped_enum) +* [`is_scoped_enum` checks whether type is an Scoped enumeration.](#is_scoped_enum) +* [`underlying_type` improved UB-free "SFINAE-friendly" std::underlying_type.](#underlying_type) +* [`ostream_operators` ostream operators for enums.](#ostream_operators) +* [`bitwise_operators` bitwise operators for enums.](#bitwise_operators) + +# Synopsis + +* Before use, read the [limitations](limitations.md) of functionality. + +* To check is magic_enum supported compiler use macro `MAGIC_ENUM_SUPPORTED` or constexpr constant `magic_enum::is_magic_enum_supported`. + +## `enum_cast` +```cpp +template +constexpr optional enum_cast(string_view value) noexcept; + +template +constexpr optional enum_cast(underlying_type_t value) noexcept; +``` + +* Obtains enum value from string or integer. + +* Returns `std::optional`, using `has_value()` to check contains enum value and `value()` to get the enum value. + +* If argument does not enum value, returns empty `std::optional`. + +* Examples + * String to enum value. + ```cpp + std::string color_name{"GREEN"}; + auto color = magic_enum::enum_cast(color_name); + if (color.has_value()) { + // color.value() -> Color::GREEN + } + ``` + * Integer to enum value. + ```cpp + int color_integer = 2; + auto color = magic_enum::enum_cast(color_integer); + if (colo.has_value()) { + // color.value() -> Color::RED + } + ``` + +## `enum_value` +```cpp +template +constexpr E enum_value(std::size_t index) noexcept; +``` + +* Returns enum value at specified index. + +* No bounds checking is performed: the behavior is undefined if `index >= number of enum values`. + +* Examples + ```cpp + int i = 1; + Color color = magic_enum::enum_value(i); + // color -> Color::BLUE + ```` + +## `enum_values` +```cpp +template +constexpr array enum_values() noexcept; +``` + +* Returns `std::array` with all enum value where `N = number of enum values`, sorted by enum value. + +* Examples + ```cpp + constexpr auto colors = magic_enum::enum_values(); + // colors -> {Color::RED, Color::BLUE, Color::GREEN} + // colors[0] -> Color::RED + ``` + +## `enum_count` +```cpp +template +constexpr size_t enum_count() noexcept; +``` + +* Returns number of enum values. + +* Examples + ```cpp + constexpr std::size_t color_count = magic_enum::enum_count(); + // color_count -> 3 + ``` + +## `enum_integer` +```cpp +template +constexpr underlying_type_t enum_integer(E value) noexcept; +``` + +* Returns integer value from enum value. + +* Examples + ```cpp + Color color = Color::RED; + auto color_integer = magic_enum::enum_integer(color); + // color -> 2 + ``` + +## `enum_name` +```cpp +template +constexpr std::string_view enum_name(E value) noexcept; + +template +constexpr std::string_view enum_name() noexcept; +``` + +* Returns `std::string_view`. If enum value does not have name, returns empty string. + +* Examples + * Enum value to string. + ```cpp + Color color = Color::RED; + auto color_name = magic_enum::enum_name(color); + // color_name -> "RED" + ``` + * 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). + ```cpp + constexpr Color color = Color::BLUE; + constexpr auto color_name = magic_enum::enum_name(); + // color_name -> "BLUE" + ``` + +* `magic_enum::enum_name()` is much lighter on the compile times and is not restricted to the enum_range [limitation](limitation.md). + + +## `enum_names` +```cpp +template +constexpr array enum_names() noexcept; +``` + +* Returns `std::array` with all string enum name where `N = number of enum values`, sorted by enum value. + +* Examples + ```cpp + constexpr auto color_names = magic_enum::enum_names(); + // color_names -> {"RED", "BLUE", "GREEN"} + // color_names[0] -> "RED" + ``` + +## `enum_entries` +```cpp +template +constexpr array, N> enum_entries() noexcept; +``` + +* Returns `std::array, N>` with all `std::pair` (value enum, string enum name) where `N = number of enum values`, sorted by enum value. + +* Examples + ```cpp + constexpr auto color_entries = magic_enum::enum_entries(); + // color_entries -> {{Color::RED, "RED"}, {Color::BLUE, "BLUE"}, {Color::GREEN, "GREEN"}} + // color_entries[0].first -> Color::RED + // color_entries[0].second -> "RED" + ``` + +## `is_unscoped_enum` +```cpp +template +struct is_unscoped_enum; + +template +inline constexpr bool is_unscoped_enum_v = is_unscoped_enum::value; +``` + +* Checks whether type is an [Unscoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Unscoped_enumeration). + +* 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 + ```cpp + magic_enum::is_unscoped_enum::value -> true + magic_enum::is_unscoped_enum::value -> false + + // Helper variable template. + magic_enum::is_unscoped_enum_v -> true + ``` + +## `is_scoped_enum` +```cpp +template +struct is_scoped_enum; + +template +inline constexpr bool is_scoped_enum_v = is_scoped_enum::value; +``` + +* Checks whether type is an [Scoped enumeration](https://en.cppreference.com/w/cpp/language/enum#Scoped_enumerations). + +* 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 + ```cpp + magic_enum::is_scoped_enum::value -> false + magic_enum::is_scoped_enum::value -> true + + // Helper variable template. + magic_enum::is_scoped_enum_v -> true + ``` + +## `underlying_type` + +```cpp +template +struct underlying_type; + +template +using underlying_type_t = typename underlying_type::type; +``` + +* Improved UB-free "SFINAE-friendly" [std::underlying_type](https://en.cppreference.com/w/cpp/types/underlying_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. + +* Examples + ```cpp + magic_enum::underlying_type::type -> int + + // Helper types. + magic_enum::underlying_type_t -> int + ``` + +## `ostream_operators` +```cpp +template +std::basic_ostream& operator<<(std::basic_ostream& os, E value); + +template +std::basic_ostream& operator<<(std::basic_ostream& os, std::optional value); + +``` +* Out-of-the-box ostream operators for enums. + +* Examples + ```cpp + using namespace magic_enum::ostream_operators; // out-of-the-box ostream operators for enums. + Color color = Color::BLUE; + std::cout << color << std::endl; // "BLUE" + ``` + +## `bitwise_operators` +```cpp +template +constexpr E operator~(E rhs) noexcept; + +template +constexpr E operator|(E lhs, E rhs) noexcept; + +template +constexpr E operator&(E lhs, E rhs) noexcept; + +template +constexpr E operator^(E lhs, E rhs) noexcept; + +template +constexpr E& operator|=(E& lhs, E rhs) noexcept; + +template +constexpr E& operator&=(E& lhs, E rhs) noexcept; + +template +constexpr E& operator^=(E& lhs, E rhs) noexcept; +``` + +* Out-of-the-box bitwise operators for enums. + +* Examples + ```cpp + 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. + // Support operators: ~, |, &, ^, |=, &=, ^=. + Flags flags = Flags::A | Flags::B & ~Flags::C; + ```