add flags (#43)

README.md

@@ -199,6 +199,8 @@ enum class Color { RED = 2, BLUE = 4, GREEN = 8 };
 
 * Before use, read the [limitations](doc/limitations.md) of functionality.
 
+* For the small enum use the API from the namespace `magic_enum`, and for enum-flags use the API from the namespace `magic_enum::flags`.
+
 ## Integration
 
 You should add the required file [magic_enum.hpp](include/magic_enum.hpp).

doc/limitations.md

@@ -38,7 +38,7 @@
     } // namespace magic_enum
     ```
 
-* `magic_enum` won't work if a value is aliased, work with enum-aliases is compiler-implementation-defined.
+* `magic_enum` won't work if a value is aliased. Work with enum-aliases is compiler-implementation-defined.
 
   ```cpp
   enum ShapeKind {
@@ -80,8 +80,7 @@
   // magic_enum::enum_name(ShapeKind::ConvexBegin) -> "Box"
   ```
 
-  On some compiler enum-aliases not supported:
+  On some compiler enum-aliases not supported, [for example Visual Studio 2017](https://github.com/Neargye/magic_enum/issues/36).
-  * <https://github.com/Neargye/magic_enum/issues/36>
 
 * If you hit a message like this:
 

doc/reference.md

@@ -24,14 +24,19 @@
 * To check is magic_enum supported compiler use macro `MAGIC_ENUM_SUPPORTED` or constexpr constant `magic_enum::is_magic_enum_supported`.</br>
   If magic_enum used on unsupported compiler, occurs the compilation error. To suppress error define macro `MAGIC_ENUM_NO_CHECK_SUPPORT`.
 
+* For the small enum use the API from the namespace `magic_enum`, and for enum-flags use the API from the namespace `magic_enum::flags`.
+
 ## `enum_cast`
 
 ```cpp
 template <typename E>
-constexpr optional<E> enum_cast(string_view value) noexcept;
+constexpr optional<E> enum_cast(underlying_type_t<E> value) noexcept;
 
 template <typename E>
-constexpr optional<E> enum_cast(underlying_type_t<E> value) noexcept;
+constexpr optional<E> enum_cast(string_view value) noexcept;
+
+template <typename E, typename BinaryPredicate>
+constexpr optional<E> enum_cast(string_view value, BinaryPredicate p) noexcept(is_nothrow_invocable_v<BinaryPredicate>);
 ```
 
 * Obtains enum value from string or integer.
@@ -88,7 +93,7 @@ template <typename E>
 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 values where `N = number of enum values`, sorted by enum value.
 
 * Examples
 
@@ -141,7 +146,7 @@ template <auto V>
 constexpr string_view enum_name() noexcept;
 ```
 
-* Returns `std::string_view` with null-terminated string enum name from enum value.
+* Returns `std::string_view` with null-terminated string name from enum value.
   * If enum value does not have name or [out of range](limitations.md), `enum_name(value)` returns empty string.
   * If enum value does not have name, `enum_name<value>()` occurs the compilation error `"Enum value does not have a name."`.
 
@@ -172,7 +177,7 @@ template <typename E>
 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 names where `N = number of enum values`, sorted by enum value.
 
 * Examples
 
@@ -189,7 +194,7 @@ template <typename E>
 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 pairs (enum value, string name) where `N = number of enum values`, sorted by enum value.
 
 * Examples
 
@@ -207,7 +212,7 @@ template <typename E>
 constexpr optional<size_t> enum_index() noexcept;
 ```
 
-* Obtains index in enum value sequence from enum value.
+* Obtains index in enum values from enum value.
 
 * Returns `std::optional<std::size_t>` with index.
 
@@ -224,8 +229,15 @@ constexpr optional<size_t> enum_index() noexcept;
 ```cpp
 template <typename E>
 constexpr bool enum_contains(E value) noexcept;
+
+template <typename E>
 constexpr bool enum_contains(underlying_type_t<E> value) noexcept;
+
+template <typename E>
 constexpr bool enum_contains(string_view value) noexcept;
+
+template <typename E, typename BinaryPredicate>
+constexpr optional<E> enum_contains(string_view value, BinaryPredicate p) noexcept(is_nothrow_invocable_v<BinaryPredicate>);
 ```
 
 * Checks whether enum contains enumerator with such value.

example/CMakeLists.txt

@@ -9,8 +9,13 @@ elseif(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
     endif()
 endif()
 
-add_executable(example example.cpp)
+function(make_example target)
-set_target_properties(example PROPERTIES CXX_EXTENSIONS OFF)
+    add_executable(${target} ${target}.cpp)
-target_compile_features(example PRIVATE cxx_std_17)
+    set_target_properties(${target} PROPERTIES CXX_EXTENSIONS OFF)
-target_compile_options(example PRIVATE ${OPTIONS})
+    target_compile_features(${target} PRIVATE cxx_std_17)
-target_link_libraries(example PRIVATE ${CMAKE_PROJECT_NAME})
+    target_compile_options(${target} PRIVATE ${OPTIONS})
+    target_link_libraries(${target} PRIVATE ${CMAKE_PROJECT_NAME})
+endfunction()
+
+make_example(example)
+make_example(enum_flag_example)

example/enum_flag_example.cpp

@@ -0,0 +1,95 @@
+// Licensed under the MIT License <http://opensource.org/licenses/MIT>.
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2019 - 2020 Daniil Goncharov <neargye@gmail.com>.
+//
+// Permission is hereby  granted, free of charge, to any  person obtaining a copy
+// of this software and associated  documentation files (the "Software"), to deal
+// in the Software  without restriction, including without  limitation the rights
+// to  use, copy,  modify, merge,  publish, distribute,  sublicense, and/or  sell
+// copies  of  the Software,  and  to  permit persons  to  whom  the Software  is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE  IS PROVIDED "AS  IS", WITHOUT WARRANTY  OF ANY KIND,  EXPRESS OR
+// IMPLIED,  INCLUDING BUT  NOT  LIMITED TO  THE  WARRANTIES OF  MERCHANTABILITY,
+// FITNESS FOR  A PARTICULAR PURPOSE AND  NONINFRINGEMENT. IN NO EVENT  SHALL THE
+// AUTHORS  OR COPYRIGHT  HOLDERS  BE  LIABLE FOR  ANY  CLAIM,  DAMAGES OR  OTHER
+// LIABILITY, WHETHER IN AN ACTION OF  CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE  OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include <iostream>
+#include <string>
+
+#include <magic_enum.hpp>
+
+enum class AnimalFlags : std::uint64_t { HasClaws = 1 << 10, CanFly = 1 << 20, EatsFish = 1 << 30, Endangered = std::uint64_t{1} << 40 };
+
+int main() {
+  // Enum variable to string name.
+  AnimalFlags f1 = AnimalFlags::Endangered;
+  auto f1_name = magic_enum::flags::enum_name(f1);
+  std::cout << f1_name << std::endl; // Endangered
+
+  // String enum name sequence.
+  constexpr auto& names = magic_enum::flags::enum_names<AnimalFlags>();
+  std::cout << "AnimalFlags names:";
+  for (const auto& n : names) {
+    std::cout << " " << n;
+  }
+  std::cout << std::endl;
+  // AnimalFlags names: HasClaws CanFly EatsFish Endangered
+
+  // String name to enum value.
+  auto f2 = magic_enum::flags::enum_cast<AnimalFlags>("EatsFish|CanFly");
+  if (f2.has_value()) {
+    std::cout << "EatsFish = " << magic_enum::flags::enum_integer(f2.value()) << std::endl; // CanFly|EatsFish = 1074790400
+  }
+
+  // Integer value to enum value.
+  auto f3 = magic_enum::flags::enum_cast<AnimalFlags>(1073742848);
+  if (f3.has_value()) {
+    std::cout << magic_enum::flags::enum_name(f3.value()) << " = " << magic_enum::flags::enum_integer(f3.value()) << std::endl; // HasClaws|EatsFish = 1073742848
+  }
+
+  // Enum value to integer value.
+  auto f4_integer = magic_enum::flags::enum_integer(AnimalFlags::HasClaws);
+  std::cout << "HasClaws = " << f4_integer << std::endl; // HasClaws = 1024
+
+  using namespace magic_enum::flags::ostream_operators; // out-of-the-box ostream operator for all enums.
+  // ostream operator for enum.
+  std::cout << f1 << " " << f2 << " " << f3 << std::endl; // Endangered CanFly|EatsFish HasClaws|EatsFish
+
+  // Number of enum values.
+  std::cout << "AnimalFlags enum size: " << magic_enum::flags::enum_count<AnimalFlags>() << std::endl; // AnimalFlags enum size: 4
+
+  // Indexed access to enum value.
+  std::cout << "AnimalFlags[0] = " << magic_enum::flags::enum_value<AnimalFlags>(0) << std::endl; // AnimalFlags[0] = HasClaws
+
+  // Enum value sequence.
+  constexpr auto& values = magic_enum::flags::enum_values<AnimalFlags>();
+  std::cout << "AnimalFlags values:";
+  for (const auto& f : values) {
+    std::cout << " " << f; // ostream operator for enum.
+  }
+  std::cout << std::endl;
+  // AnimalFlags sequence: HasClaws CanFly EatsFish Endangered
+
+  using namespace magic_enum::flags::bitwise_operators; // out-of-the-box bitwise operators for all enums.
+  // Support operators: ~, |, &, ^, |=, &=, ^=.
+  AnimalFlags flag = AnimalFlags::HasClaws | AnimalFlags::CanFly;
+  std::cout << flag << std::endl; // HasClaws|CanFly
+
+  // Enum pair (value enum, string enum name) sequence.
+  constexpr auto& entries = magic_enum::flags::enum_entries<AnimalFlags>();
+  std::cout << "AnimalFlags entries:";
+  for (const auto& e : entries) {
+    std::cout << " "  << e.second << " = " << magic_enum::flags::enum_integer(e.first);
+  }
+  std::cout << std::endl;
+  // AnimalFlags entries: AnimalFlags entries: HasClaws = 1024 CanFly = 1048576 EatsFish = 1073741824 Endangered = 1099511627776
+
+  return 0;
+}

example/example.cpp

@@ -39,9 +39,9 @@ int main() {
   std::cout << c1_name << std::endl; // RED
 
   // String enum name sequence.
-  constexpr auto color_names = magic_enum::enum_names<Color>();
+  constexpr auto& names = magic_enum::enum_names<Color>();
   std::cout << "Color names:";
-  for (auto n : color_names) {
+  for (const auto& n : names) {
     std::cout << " " << n;
   }
   std::cout << std::endl;
@@ -49,36 +49,34 @@ int main() {
 
   // String name to enum value.
   auto c2 = magic_enum::enum_cast<Color>("BLUE");
-  if (c2.has_value() && c2.value() == Color::BLUE) {
+  if (c2.has_value()) {
     std::cout << "BLUE = " << to_integer(c2.value()) << std::endl; // BLUE = 0
   }
 
   // Integer value to enum value.
   auto c3 = magic_enum::enum_cast<Color>(10);
-  if (c3.has_value() && c3.value() == Color::GREEN) {
+  if (c3.has_value()) {
     std::cout << "GREEN = " << magic_enum::enum_integer(c3.value()) << std::endl; // GREEN = 10
   }
 
   // Enum value to integer value.
-  auto color_integer = magic_enum::enum_integer(c1);
+  auto c4_integer = magic_enum::enum_integer(Color::RED);
-  if (color_integer == to_integer(Color::RED)) {
+  std::cout << "RED = " << c4_integer << std::endl; // RED = -10
-    std::cout << "RED = " << color_integer << std::endl; // RED = -10
-  }
 
   using namespace magic_enum::ostream_operators; // out-of-the-box ostream operator for all enums.
   // ostream operator for enum.
   std::cout << "Color: " << c1 << " " << c2 << " " << c3 << std::endl; // Color: RED BLUE GREEN
 
   // Number of enum values.
-  std::cout << "Color enum size: " << magic_enum::enum_count<Color>() << std::endl; // Color enum size: 3
+  std::cout << "Color enum size: " << magic_enum::enum_count<Color>() << std::endl; // Color size: 3
 
   // Indexed access to enum value.
   std::cout << "Color[0] = " << magic_enum::enum_value<Color>(0) << std::endl; // Color[0] = RED
 
   // Enum value sequence.
-  constexpr auto colors = magic_enum::enum_values<Color>();
+  constexpr auto& values = magic_enum::enum_values<Color>();
-  std::cout << "Colors sequence:";
+  std::cout << "Colors values:";
-  for (Color c : colors) {
+  for (const auto& c : values) {
     std::cout << " " << c; // ostream operator for enum.
   }
   std::cout << std::endl;
@@ -87,8 +85,8 @@ int main() {
   enum class Flags { A = 1, B = 2, C = 4, D = 8 };
   using namespace magic_enum::bitwise_operators; // out-of-the-box bitwise operators for all enums.
   // Support operators: ~, |, &, ^, |=, &=, ^=.
-  Flags flags = Flags::A | Flags::C;
+  Flags flag = Flags::A | Flags::C;
-  std::cout << flags << std::endl;
+  std::cout << flag << std::endl; // 5
 
   enum color { red, green, blue };
 
@@ -103,9 +101,9 @@ int main() {
   static_assert(magic_enum::is_scoped_enum_v<Flags>);
 
   // Enum pair (value enum, string enum name) sequence.
-  constexpr auto color_entries = magic_enum::enum_entries<Color>();
+  constexpr auto& entries = magic_enum::enum_entries<Color>();
   std::cout << "Colors entries:";
-  for (auto e : color_entries) {
+  for (const auto& e : entries) {
     std::cout << " "  << e.second << " = " << static_cast<int>(e.first);
   }
   std::cout << std::endl;

test/test.cpp

@@ -27,6 +27,10 @@
 #define MAGIC_ENUM_RANGE_MAX 120
 #include <magic_enum.hpp>
 
+#if defined(_MSC_VER) && _MSC_VER >= 1920  || defined(__clang__) && __clang_major__ >= 5 || defined(__GNUC__) && __GNUC__ >= 9
+#  define MAGIC_ENUM_SUPPORTED_ALIASES
+#endif
+
 #include <array>
 #include <cctype>
 #include <string_view>
@@ -44,9 +48,7 @@ enum number : unsigned long {
   three = 300,
   four = 400,
 
-#if defined(_MSC_VER) && _MSC_VER >= 1920
+#if defined(MAGIC_ENUM_SUPPORTED_ALIASES)
-  // Aliases won't work on vs2017.
-
   _1 = one,
   _2 = two,
   _3 = three,
@@ -260,7 +262,7 @@ TEST_CASE("enum_contains") {
     constexpr auto cr = "RED";
     REQUIRE(enum_contains<Color>(cr));
     REQUIRE(enum_contains<Color&>("GREEN"));
-    REQUIRE(enum_contains<Color>("BLUE"));
+    REQUIRE(enum_contains<Color>("blue", [](char lhs, char rhs) { return std::tolower(lhs) == std::tolower(rhs); }));
     REQUIRE_FALSE(enum_contains<Color>("None"));
 
     constexpr auto no = std::string_view{"one"};
@@ -310,6 +312,8 @@ TEST_CASE("enum_value") {
 }
 
 TEST_CASE("enum_values") {
+  REQUIRE(std::is_same_v<decltype(magic_enum::enum_values<Color>()), const std::array<Color, 3>&>);
+
   constexpr auto s1 = enum_values<Color&>();
   REQUIRE(s1 == std::array<Color, 3>{{Color::RED, Color::GREEN, Color::BLUE}});
 
@@ -406,6 +410,8 @@ TEST_CASE("enum_name") {
 }
 
 TEST_CASE("enum_names") {
+  REQUIRE(std::is_same_v<decltype(magic_enum::enum_names<Color>()), const std::array<std::string_view, 3>&>);
+
   constexpr auto s1 = enum_names<Color&>();
   REQUIRE(s1 == std::array<std::string_view, 3>{{"RED", "GREEN", "BLUE"}});
 
@@ -420,6 +426,8 @@ TEST_CASE("enum_names") {
 }
 
 TEST_CASE("enum_entries") {
+  REQUIRE(std::is_same_v<decltype(magic_enum::enum_entries<Color>()), const std::array<std::pair<Color, std::string_view>, 3>&>);
+
   constexpr auto s1 = enum_entries<Color&>();
   REQUIRE(s1 == std::array<std::pair<Color, std::string_view>, 3>{{{Color::RED, "RED"}, {Color::GREEN, "GREEN"}, {Color::BLUE, "BLUE"}}});
 
@@ -567,16 +575,16 @@ TEST_CASE("type_traits") {
   REQUIRE_FALSE(is_scoped_enum_v<number>);
 }
 
-
+/* TODO: https://github.com/Neargye/nameof/issues/22
 TEST_CASE("enum_type_name") {
   REQUIRE(enum_type_name<Color&>() == "Color");
   REQUIRE(enum_type_name<Numbers>() == "Numbers");
   REQUIRE(enum_type_name<Directions&>() == "Directions");
   REQUIRE(enum_type_name<number>() == "number");
 }
+*/
 
-#if defined(_MSC_VER) && _MSC_VER >= 1920
+#if defined(MAGIC_ENUM_SUPPORTED_ALIASES)
-// Aliases won't work on vs2017.
 TEST_CASE("aliases") {
   REQUIRE(enum_count<number>() == 3);