Repository files navigation

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

If you like this project, please consider donating to one of the funds that help victims of the war in Ukraine:https://u24.gov.ua.

• Reference
• Limitations
• Integration

• Basic

  #include<magic_enum/magic_enum.hpp>#include<iostream>enumclassColor { RED = -10, BLUE =0, GREEN =10 };intmain() {  Color c1 = Color::RED;  std::cout <<magic_enum::enum_name(c1) << std::endl;// REDreturn0;}

• 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}// case insensitive enum_castauto color = magic_enum::enum_cast<Color>(value, magic_enum::case_insensitive);// enum_cast with BinaryPredicateauto color = magic_enum::enum_cast<Color>(value, [](char lhs,char rhs) {returnstd::tolower(lhs) ==std::tolower(rhs); }// enum_cast with defaultauto color_or_default = magic_enum::enum_cast<Color>(value).value_or(Color::NONE);

• Integer to enum value

  int color_integer =2;auto color = magic_enum::enum_cast<Color>(color_integer);if (color.has_value()) {// color.value() -> Color::BLUE}auto color_or_default = magic_enum::enum_cast<Color>(value).value_or(Color::NONE);

• Indexed access to enum value

  std::size_t i =0;Color color = magic_enum::enum_value<Color>(i);// color -> Color::RED

• Enum value sequence

  constexprauto 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);// or magic_enum::enum_underlying(color);// color_integer -> 1

• Enum names sequence

  constexprauto color_names = magic_enum::enum_names<Color>();// color_names -> {"RED", "BLUE", "GREEN"}// color_names[0] -> "RED"

• Enum entries sequence

  constexprauto 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()) {casemagic_enum::enum_fuse(Color::RED, Directions::Up).value():// ...casemagic_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;// ...});

• Check if enum contains

  magic_enum::enum_contains(Color::GREEN);// -> truemagic_enum::enum_contains<Color>(2);// -> truemagic_enum::enum_contains<Color>(123);// -> falsemagic_enum::enum_contains<Color>("GREEN");// -> truemagic_enum::enum_contains<Color>("fda");// -> false

• Enum index in sequence

  constexprauto color_index = magic_enum::enum_index(Color::BLUE);// color_index.value() -> 1// color_index.has_value() -> true

• Functions for flags

  enum Directions : std::uint64_t {  Left =1,  Down =2,  Up =4,  Right =8,};template<>structmagic_enum::customize::enum_range<Directions> {staticconstexprbool is_flags =true;};magic_enum::enum_flags_name(Directions::Up | Directions::Right);// -> "Directions::Up|Directions::Right"magic_enum::enum_flags_contains(Directions::Up | Directions::Right);// -> truemagic_enum::enum_flags_cast(3);// -> "Directions::Left|Directions::Down"

• Enum type name

  Color color = Color::RED;auto type_name = magic_enum::enum_type_name<decltype(color)>();// type_name -> "Color"

• IOstream operator for enum

  using magic_enum::iostream_operators::operator<<;// out-of-the-box ostream operators for enums.Color color = Color::BLUE;std::cout << color << std::endl;// "BLUE"

  using magic_enum::iostream_operators::operator>>;// out-of-the-box istream operators for enums.Color color;std::cin >> color;

• Bitwise operator for enum

  enumclassFlags { A =1 <<0, B =1 <<1, C =1 <<2, D =1 <<3 };usingnamespacemagic_enum::bitwise_operators;// out-of-the-box bitwise operators for enums.// Support operators: ~, |, &, ^, |=, &=, ^=.Flags flags = Flags::A | Flags::B & ~Flags::C;

• Checks whether type is anUnscoped enumeration.

  enum color { red, green, blue };enumclassdirection { left, right };magic_enum::is_unscoped_enum<color>::value ->truemagic_enum::is_unscoped_enum<direction>::value ->falsemagic_enum::is_unscoped_enum<int>::value ->false// Helper variable template.magic_enum::is_unscoped_enum_v<color> ->true

• Checks whether type is anScoped enumeration.

  enum color { red, green, blue };enumclassdirection { left, right };magic_enum::is_scoped_enum<color>::value ->falsemagic_enum::is_scoped_enum<direction>::value ->truemagic_enum::is_scoped_enum<int>::value ->false// Helper variable template.magic_enum::is_scoped_enum_v<direction> ->true

• Static storage enum variable to stringThis version is much lighter on the compile times and is not restricted to the enum_rangelimitation.

  constexpr Color color = Color::BLUE;constexprauto color_name = magic_enum::enum_name<color>();// color_name -> "BLUE"

• containers::array array container for enums.

  magic_enum::containers::array<Color, RGB> color_rgb_array {};color_rgb_array[Color::RED] = {255,0,0};color_rgb_array[Color::GREEN] = {0,255,0};color_rgb_array[Color::BLUE] = {0,0,255};magic_enum::containers::get<Color::BLUE>(color_rgb_array)// -> RGB{0, 0, 255}

• containers::bitset bitset container for enums.

  constexpr magic_enum::containers::bitset<Color> color_bitset_red_green {Color::RED|Color::GREEN};bool all = color_bitset_red_green.all();// all -> false// Color::BLUE is missingbool test = color_bitset_red_green.test(Color::RED);// test -> true

• containers::set set container for enums.

  auto color_set = magic_enum::containers::set<Color>();bool empty = color_set.empty();// empty -> truecolor_set.insert(Color::GREEN);color_set.insert(Color::BLUE);color_set.insert(Color::RED);std::size_t size = color_set.size();// size -> 3

• Improved UB-free "SFINAE-friendly"underlying_type.

  magic_enum::underlying_type<color>::type ->int// Helper types.magic_enum::underlying_type_t<Direction> ->int

• magic_enum does not pretend to be a silver bullet for reflection for enums, it was originally designed for small enum.

• Before use, read thelimitations of functionality.

• You should add the required filemagic_enum.hpp, and optionally other headers frominclude dir orrelease archive. Alternatively, you can build the library with CMake.

• If you are usingvcpkg on your project for external dependencies, then you can use themagic-enum package.

• If you are usingConan to manage your dependencies, merely addmagic_enum/x.y.z to your conan's requires, wherex.y.z is the release version you want to use.

• If you are usingBuild2 to build and manage your dependencies, adddepends: magic_enum ^x.y.z to the manifest file wherex.y.z is the release version you want to use. You can then import the target usingmagic_enum%lib{magic_enum}.

• Alternatively, you can use something likeCPM which is based on CMake'sFetch_Content module.

  CPMAddPackage(NAME magic_enum    GITHUB_REPOSITORY Neargye/magic_enum    GIT_TAG vx.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 withexport CC= <compiler>.)

• If you are usingRos, 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)

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