magic_enum repository

Repository Summary

Checkout URI https://github.com/Neargye/magic_enum.git
VCS Type git
VCS Version master
Last Updated 2022-09-02
Dev Status MAINTAINED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

Name Version
magic_enum 0.8.1

README

Stand With Ukraine

 __  __             _        ______                          _____
|  \/  |           (_)      |  ____|                        / ____|_     _
| \  / | __ _  __ _ _  ___  | |__   _ __  _   _ _ __ ___   | |   _| |_ _| |_
| |\/| |/ _` |/ _` | |/ __| |  __| | '_ \| | | | '_ ` _ \  | |  |_   _|_   _|
| |  | | (_| | (_| | | (__  | |____| | | | |_| | | | | | | | |____|_|   |_|
|_|  |_|\__,_|\__, |_|\___| |______|_| |_|\__,_|_| |_| |_|  \_____|
               __/ |
              |___/

Github releases Conan package Vcpkg package Build2 package License Try online Compiler explorer

Magic Enum C++

Header-only C++17 library provides static reflection for enums, work with any enum type without any macro or boilerplate code.

  • enum_cast obtains enum value from string or integer.
  • enum_value returns enum value at specified index.
  • enum_values obtains enum value sequence.
  • enum_count returns number of enum values.
  • enum_integer obtains integer value from enum value.
  • enum_name returns name from enum value.
  • enum_names obtains string enum name sequence.
  • enum_entries obtains pair (value enum, string enum name) sequence.
  • enum_index obtains index in enum value sequence from enum value.
  • enum_contains checks whether enum contains enumerator with such value.
  • enum_type_name returns name of enum type.
  • enum_fuse allows multidimensional switch/cases.
  • enum_switch allows runtime enum value transformation to constexpr context.
  • enum_for_each calls a function with all enum constexpr value.
  • is_unscoped_enum checks whether type is an Unscoped enumeration.
  • is_scoped_enum checks whether type is an Scoped enumeration.
  • underlying_type improved UB-free "SFINAE-friendly" underlying_type.
  • ostream_operators ostream operators for enums.
  • bitwise_operators bitwise operators for enums.

Documentation

Features

  • C++17
  • Header-only
  • Dependency-free
  • Compile-time
  • Enum to string
  • String to enum
  • Iterating over enum

Examples

// For example color enum.
enum class Color { RED = 2, BLUE = 4, GREEN = 8 };

  • Enum value to string
  Color color = Color::RED;
  auto color_name = magic_enum::enum_name(color);
  // color_name -> "RED"

  • String to enum value
  std::string color_name{"GREEN"};
  auto color = magic_enum::enum_cast<Color>(color_name);
  if (color.has_value()) {
    // color.value() -> Color::GREEN
  }

  • Integer to enum value
  int color_integer = 2;
  auto color = magic_enum::enum_cast<Color>(color_integer);
  if (color.has_value()) {
    // color.value() -> Color::RED
  }

  • Indexed access to enum value
  std::size_t i = 1;
  Color color = magic_enum::enum_value<Color>(i);
  // color -> Color::BLUE

  • Enum value sequence
  constexpr auto colors = magic_enum::enum_values<Color>();
  // colors -> {Color::RED, Color::BLUE, Color::GREEN}
  // colors[0] -> Color::RED

  • Number of enum elements
  constexpr std::size_t color_count = magic_enum::enum_count<Color>();
  // color_count -> 3

  • Enum value to integer
  Color color = Color::RED;
  auto color_integer = magic_enum::enum_integer(color);
  // color -> 2

  • Enum names sequence
  constexpr auto color_names = magic_enum::enum_names<Color>();
  // color_names -> {"RED", "BLUE", "GREEN"}
  // color_names[0] -> "RED"

  • Enum entries sequence
  constexpr auto color_entries = magic_enum::enum_entries<Color>();
  // color_entries -> {{Color::RED, "RED"}, {Color::BLUE, "BLUE"}, {Color::GREEN, "GREEN"}}
  // color_entries[0].first -> Color::RED
  // color_entries[0].second -> "RED"

  • Enum fusion for multi-level switch/case statements
  switch (magic_enum::enum_fuse(color, direction).value()) {
    case magic_enum::enum_fuse(Color::RED, Directions::Up).value(): // ...
    case magic_enum::enum_fuse(Color::BLUE, Directions::Down).value(): // ...
  // ...
  }

  • Enum switch runtime value as constexpr constant
  Color color = Color::RED;

  magic_enum::enum_switch([] (auto val) {
    constexpr Color c_color = val;
    // ...
  }, color);

  • Enum iterate for each enum as constexpr constant
  magic_enum::enum_for_each<Color>([] (auto val) {
    constexpr Color c_color = val;
    // ...
  });

  • Ostream operator for enum
  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 operator for enum
  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;

  enum color { red, green, blue };
  enum class direction { left, right };

  magic_enum::is_unscoped_enum<color>::value -> true
  magic_enum::is_unscoped_enum<direction>::value -> false
  magic_enum::is_unscoped_enum<int>::value -> false

  // Helper variable template.
  magic_enum::is_unscoped_enum_v<color> -> true

  enum color { red, green, blue };
  enum class direction { left, right };

  magic_enum::is_scoped_enum<color>::value -> false
  magic_enum::is_scoped_enum<direction>::value -> true
  magic_enum::is_scoped_enum<int>::value -> false

  // Helper variable template.
  magic_enum::is_scoped_enum_v<direction> -> true

  • Static storage enum variable to string This version is much lighter on the compile times and is not restricted to the enum_range limitation.
  constexpr Color color = Color::BLUE;
  constexpr auto color_name = magic_enum::enum_name<color>();
  // 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 of functionality.

Integration

  • You should add the required file magic_enum.hpp.

  • If you are using vcpkg on your project for external dependencies, then you can use the magic-enum package.

  • If you are using Conan to manage your dependencies, merely add magic_enum/x.y.z to your conan's requires, where x.y.z is the release version you want to use.

  • If you are using Build2 to build and manage your dependencies, add depends: magic_enum ^x.y.z to the manifest file where x.y.z is the release version you want to use. You can then import the target using magic_enum%lib{magic_enum}.

  • Alternatively, you can use something like CPM which is based on CMake's Fetch_Content module.

  CPMAddPackage(
      NAME magic_enum
      GITHUB_REPOSITORY Neargye/magic_enum
      GIT_TAG x.y.z # Where `x.y.z` is the release version you want to use.
  )

  • Bazel is also supported, simply add to your WORKSPACE file:
  http_archive(
      name = "magic_enum",
      strip_prefix = "magic_enum-<commit>",
      urls = ["https://github.com/Neargye/magic_enum/archive/<commit>.zip"],
  )

To use bazel inside the repository it's possible to do:

  bazel build //...
  bazel test //...
  bazel run //:example

(Note that you must use a supported compiler or specify it with export CC= <compiler>.)

  • If you are using Ros, you can include this package by adding <depend>magic_enum</depend> to your package.xml and include this package in your workspace. In your CMakeLists.txt add the following:
  find_package(magic_enum CONFIG REQUIRED)
  ...
  target_link_libraries(your_executable magic_enum::magic_enum)

Compiler compatibility

  • Clang/LLVM >= 6
  • MSVC++ >= 14.11 / Visual Studio >= 2017
  • Xcode >= 10
  • GCC >= 9
  • MinGW >= 9

Licensed under the MIT License

CONTRIBUTING

No CONTRIBUTING.md found.

Repository Summary

Checkout URI https://github.com/Neargye/magic_enum.git
VCS Type git
VCS Version master
Last Updated 2022-09-02
Dev Status MAINTAINED
CI status No Continuous Integration
Released RELEASED
Tags No category tags.
Contributing Help Wanted (0)
Good First Issues (0)
Pull Requests to Review (0)

Packages

Name Version
magic_enum 0.8.1

README

Stand With Ukraine

 __  __             _        ______                          _____
|  \/  |           (_)      |  ____|                        / ____|_     _
| \  / | __ _  __ _ _  ___  | |__   _ __  _   _ _ __ ___   | |   _| |_ _| |_
| |\/| |/ _` |/ _` | |/ __| |  __| | '_ \| | | | '_ ` _ \  | |  |_   _|_   _|
| |  | | (_| | (_| | | (__  | |____| | | | |_| | | | | | | | |____|_|   |_|
|_|  |_|\__,_|\__, |_|\___| |______|_| |_|\__,_|_| |_| |_|  \_____|
               __/ |
              |___/

Github releases Conan package Vcpkg package Build2 package License Try online Compiler explorer

Magic Enum C++

Header-only C++17 library provides static reflection for enums, work with any enum type without any macro or boilerplate code.

  • enum_cast obtains enum value from string or integer.
  • enum_value returns enum value at specified index.
  • enum_values obtains enum value sequence.
  • enum_count returns number of enum values.
  • enum_integer obtains integer value from enum value.
  • enum_name returns name from enum value.
  • enum_names obtains string enum name sequence.
  • enum_entries obtains pair (value enum, string enum name) sequence.
  • enum_index obtains index in enum value sequence from enum value.
  • enum_contains checks whether enum contains enumerator with such value.
  • enum_type_name returns name of enum type.
  • enum_fuse allows multidimensional switch/cases.
  • enum_switch allows runtime enum value transformation to constexpr context.
  • enum_for_each calls a function with all enum constexpr value.
  • is_unscoped_enum checks whether type is an Unscoped enumeration.
  • is_scoped_enum checks whether type is an Scoped enumeration.
  • underlying_type improved UB-free "SFINAE-friendly" underlying_type.
  • ostream_operators ostream operators for enums.
  • bitwise_operators bitwise operators for enums.

Documentation

Features

  • C++17
  • Header-only
  • Dependency-free
  • Compile-time
  • Enum to string
  • String to enum
  • Iterating over enum

Examples

// For example color enum.
enum class Color { RED = 2, BLUE = 4, GREEN = 8 };

  • Enum value to string
  Color color = Color::RED;
  auto color_name = magic_enum::enum_name(color);
  // color_name -> "RED"

  • String to enum value
  std::string color_name{"GREEN"};
  auto color = magic_enum::enum_cast<Color>(color_name);
  if (color.has_value()) {
    // color.value() -> Color::GREEN
  }

  • Integer to enum value
  int color_integer = 2;
  auto color = magic_enum::enum_cast<Color>(color_integer);
  if (color.has_value()) {
    // color.value() -> Color::RED
  }

  • Indexed access to enum value
  std::size_t i = 1;
  Color color = magic_enum::enum_value<Color>(i);
  // color -> Color::BLUE

  • Enum value sequence
  constexpr auto colors = magic_enum::enum_values<Color>();
  // colors -> {Color::RED, Color::BLUE, Color::GREEN}
  // colors[0] -> Color::RED

  • Number of enum elements
  constexpr std::size_t color_count = magic_enum::enum_count<Color>();
  // color_count -> 3

  • Enum value to integer
  Color color = Color::RED;
  auto color_integer = magic_enum::enum_integer(color);
  // color -> 2

  • Enum names sequence
  constexpr auto color_names = magic_enum::enum_names<Color>();
  // color_names -> {"RED", "BLUE", "GREEN"}
  // color_names[0] -> "RED"

  • Enum entries sequence
  constexpr auto color_entries = magic_enum::enum_entries<Color>();
  // color_entries -> {{Color::RED, "RED"}, {Color::BLUE, "BLUE"}, {Color::GREEN, "GREEN"}}
  // color_entries[0].first -> Color::RED
  // color_entries[0].second -> "RED"

  • Enum fusion for multi-level switch/case statements
  switch (magic_enum::enum_fuse(color, direction).value()) {
    case magic_enum::enum_fuse(Color::RED, Directions::Up).value(): // ...
    case magic_enum::enum_fuse(Color::BLUE, Directions::Down).value(): // ...
  // ...
  }

  • Enum switch runtime value as constexpr constant
  Color color = Color::RED;

  magic_enum::enum_switch([] (auto val) {
    constexpr Color c_color = val;
    // ...
  }, color);

  • Enum iterate for each enum as constexpr constant
  magic_enum::enum_for_each<Color>([] (auto val) {
    constexpr Color c_color = val;
    // ...
  });

  • Ostream operator for enum
  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 operator for enum
  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;

  enum color { red, green, blue };
  enum class direction { left, right };

  magic_enum::is_unscoped_enum<color>::value -> true
  magic_enum::is_unscoped_enum<direction>::value -> false
  magic_enum::is_unscoped_enum<int>::value -> false

  // Helper variable template.
  magic_enum::is_unscoped_enum_v<color> -> true

  enum color { red, green, blue };
  enum class direction { left, right };

  magic_enum::is_scoped_enum<color>::value -> false
  magic_enum::is_scoped_enum<direction>::value -> true
  magic_enum::is_scoped_enum<int>::value -> false

  // Helper variable template.
  magic_enum::is_scoped_enum_v<direction> -> true

  • Static storage enum variable to string This version is much lighter on the compile times and is not restricted to the enum_range limitation.
  constexpr Color color = Color::BLUE;
  constexpr auto color_name = magic_enum::enum_name<color>();
  // 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 of functionality.

Integration

  • You should add the required file magic_enum.hpp.

  • If you are using vcpkg on your project for external dependencies, then you can use the magic-enum package.

  • If you are using Conan to manage your dependencies, merely add magic_enum/x.y.z to your conan's requires, where x.y.z is the release version you want to use.

  • If you are using Build2 to build and manage your dependencies, add depends: magic_enum ^x.y.z to the manifest file where x.y.z is the release version you want to use. You can then import the target using magic_enum%lib{magic_enum}.

  • Alternatively, you can use something like CPM which is based on CMake's Fetch_Content module.

  CPMAddPackage(
      NAME magic_enum
      GITHUB_REPOSITORY Neargye/magic_enum
      GIT_TAG x.y.z # Where `x.y.z` is the release version you want to use.
  )

  • Bazel is also supported, simply add to your WORKSPACE file:
  http_archive(
      name = "magic_enum",
      strip_prefix = "magic_enum-<commit>",
      urls = ["https://github.com/Neargye/magic_enum/archive/<commit>.zip"],
  )

To use bazel inside the repository it's possible to do:

  bazel build //...
  bazel test //...
  bazel run //:example

(Note that you must use a supported compiler or specify it with export CC= <compiler>.)

  • If you are using Ros, you can include this package by adding <depend>magic_enum</depend> to your package.xml and include this package in your workspace. In your CMakeLists.txt add the following:
  find_package(magic_enum CONFIG REQUIRED)
  ...
  target_link_libraries(your_executable magic_enum::magic_enum)

Compiler compatibility

  • Clang/LLVM >= 6
  • MSVC++ >= 14.11 / Visual Studio >= 2017
  • Xcode >= 10
  • GCC >= 9
  • MinGW >= 9

Licensed under the MIT License

CONTRIBUTING

No CONTRIBUTING.md found.