{"id":28088919,"url":"https://github.com/zxshady/enchantum","last_synced_at":"2025-06-13T06:31:57.181Z","repository":{"id":289313984,"uuid":"967807282","full_name":"ZXShady/enchantum","owner":"ZXShady","description":"A Faster Enum Reflection For C++20 Since I Don't Want To Wait For C++26 Reflection","archived":false,"fork":false,"pushed_at":"2025-06-10T05:00:08.000Z","size":412,"stargazers_count":45,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-10T05:30:07.275Z","etag":null,"topics":["c-plus-plus","cpp","cpp20","enum","enum-to-string","header-only","is-bitflag-enum","metaprogramming","no-dependencies","reflection","reflection-library","serialization","string-to-enum","templates"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZXShady.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-17T03:16:02.000Z","updated_at":"2025-06-10T05:00:12.000Z","dependencies_parsed_at":"2025-04-22T17:33:40.349Z","dependency_job_id":"0a312f43-e148-4072-98c7-cc8c3e6ac2e7","html_url":"https://github.com/ZXShady/enchantum","commit_stats":null,"previous_names":["zxshady/enchantum"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ZXShady/enchantum","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZXShady%2Fenchantum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZXShady%2Fenchantum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZXShady%2Fenchantum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZXShady%2Fenchantum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZXShady","download_url":"https://codeload.github.com/ZXShady/enchantum/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZXShady%2Fenchantum/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259594268,"owners_count":22881630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-plus-plus","cpp","cpp20","enum","enum-to-string","header-only","is-bitflag-enum","metaprogramming","no-dependencies","reflection","reflection-library","serialization","string-to-enum","templates"],"created_at":"2025-05-13T12:52:28.607Z","updated_at":"2025-06-13T06:31:57.164Z","avatar_url":"https://github.com/ZXShady.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Enchantum\n\n**Enchantum** (short for \"enchant enum\") is a modern **C++20** header-only library for **compile-time enum reflection**. It provides fast, lightweight access to enum values, names, and bitflags all without macros or boilerplate.\n\n\u003e Every year, countless turtles perish due to the pollution caused by slow, bloated build times.  \n Save the turtles — and your compile times — by switching to enchantum!\n\n\u003csup\u003e\u003csub\u003eSource: I made it up.\u003c/sup\u003e\u003c/sub\u003e\n\nKey Features\n\n  - Macro-free and non-intrusive boilerplate-free reflection\n\n  - Fast compile times (benchmarked below)\n\n  - Most efficient binary size wise.\n  \n  - Supports:\n       -  Scoped enums\n       -  Unscoped C enums\n       -  Sparse enums\n       -  Bitflags\n       -  Iteration over values,names and `[enum, name]` pairs.\n       -  `string \u003c=\u003e enum` conversions\n       -  `enum \u003c=\u003e index` conversions\n       -  enum validation functions like `cast` and `contains`\n       -  enum aware containers: `enchantum::bitset` and `enchantum::array`\n  - Extra features like:\n      - Optional null terminator disabling\n      - Optional prefix stripping for C-style enums\n      - `0` values are reflected for bitflag enums \n\n[Simple Examples](#simple-examples)\n\n[Why another enum reflection library?](#why-another-enum-reflection-library)\n\n[Features](docs/features.md)\n\n[Benchmarks](#benchmarks)\n\n[Limitations](docs/limitations.md)\n\n[CMake Integration](#cmake-integration)\n\nTested locally on Windows 10 with:\n- Visual Studio 2022 (v17.13.6)\n- GCC 14.2.0\n- Clang 20.1.2\n\nCompiler Support: (Look at [CI](https://github.com/ZXShady/enchantum/actions))\n- GCC \u003e= 11 (GCC 10 Partial no support for enums in templates)\n- Clang \u003e= 10\n\n---\n\n\u003e [!IMPORTANT]\n\u003e Be sure to read [Limitations](docs/limitations.md) before using Enchantum in production.\n\n## Simple Examples\n\nEnums used in the examples\n\n* to string\n```cpp\n#include \u003cenchantum/enchantum.hpp\u003e // to_string\n#include \u003cenchantum/ostream.hpp\u003e // ostream support\nenum class Music { Rock, Jazz , Metal };\n\nint main() \n{\n  auto music = Music::Rock;\n  std::string_view music_name =  enchantum::to_string(music);\n  // music_name == \"Rock\"\n\n  using namespace enchantum::ostream_operators;\n  std::cout \u003c\u003c music;\n  // Prints Rock\n}\n```\n\n* from strings\n```cpp\n#include \u003cenchantum/enchantum.hpp\u003e // cast\nenum class Music { Rock, Jazz , Metal };\nint main() \n{\n  // case sensitive\n  std::optional\u003cMusic\u003e music = enchantum::cast\u003cMusic\u003e(\"Jazz\");\n  if(music.has_value()) // check if cast succeeded\n  {\n    // *music == Music::Jazz\n  }\n  // pass a predicate taking two string views\n  music = enchantum::cast\u003cMusic\u003e(\"JAZZ\",[](std::string_view a,std::string_view b){\n    return std::ranges::equal(a,b,[](unsigned char x,unsigned char y){\n      return std::tolower(x) == std::tolower(y);      \n    });\n  });\n  if(music.has_value()) {\n      // *music == Music::Jazz\n  }\n}\n```\n\n* index into enums\n```cpp\n#include \u003cenchantum/enchantum.hpp\u003e // index_to_enum and enum_to_index\nenum class Music { Rock, Jazz , Metal };\n\nint main() \n{\n  // case sensitive\n  std::optional\u003cMusic\u003e music = enchantum::index_to_enum\u003cMusic\u003e(1); // Jazz is the second enum member\n  if(music.has_value()) // check if index is not out of bounds\n  {\n    // *music == Music::Jazz\n    std::optional\u003cstd::size_t\u003e index = enchantum::enum_to_index(*music);\n    // *index == 1\n  }\n}\n```\n\n* iteration\n```cpp\n#include \u003cenchantum/enchantum.hpp\u003e // entries,values and names \nenum class Music { Rock, Jazz , Metal };\n\nint main() \n{\n  // Iterate over values\n  for(Music music : enchantum::values\u003cMusic\u003e)\n    std::cout \u003c\u003c static_cast\u003cint\u003e(music) \u003c\u003c \" \";\n  // Prints \"0 1 2\"\n\n  // Iterate over names\n  for(std::string_view name : enchantum::names\u003cMusic\u003e)\n    std::cout \u003c\u003c name \u003c\u003c \" \";\n  // Prints \"Rock Jazz Metal\"\n\n  // Iterate over both!\n  for(const auto\u0026 [music,name] : enchantum::entries\u003cMusic\u003e)\n    std::cout \u003c\u003c name \u003c\u003c \" = \" \u003c\u003c static_cast\u003cint\u003e(music) \u003c\u003c \"\\n\";\n  // Prints \n  // Rock = 0\n  // Jazz = 1\n  // Metal = 2\n}\n```\n\nLook at [Features](docs/features.md) for more information.\n\n\n## Why Another Enum Reflection Library?\n\nThere are several enum reflection libraries out there — so why choose **enchantum** instead of [magic_enum](https://github.com/Neargye/magic_enum), [simple_enum](https://github.com/arturbac/simple_enum), or [conjure_enum](https://github.com/fix8mt/conjure_enum)?\n\n\n### magic_enum\n\n**Pros**\n- Macro-free (non intrusive).\n- No modifications needed for existing enums.\n- Allows specifying ranges for specific enums when needed.\n- Supports C++17.\n- Nicer compiler errors.\n- Supports wide strings.\n- Efficient executable binary size.\n\n**Cons**\n- Compile times grow significantly with larger `MAGIC_ENUM_MAX_RANGE`. \n- Bigger Binary Size.\n\n### conjure_enum\n\n**Pros**\n- Macro-free (non intrusive)\n- Uses C++20\n\n**Cons**\n\n*Note: Could not get this to compile locally. Based on the README, compile times are similar to or worse than magic_enum.*\n\n### simple_enum\n\n**Pros**\n- Fast compile times but only if range is small.\n- Functor based api.\n\n**Cons**\n- Requires specifying enum `first`/`last` values manually (intrusive, doesn't work well with third-party enums)\n- Compile time slows down with large enum ranges\n- Big Binary Size Bloat.\n- No support for bitflags yet.\n\n### enchantum\n\n**Pros**\n- Macro-free (non intrusive)\n- Does not sacrifice API ease of use and features for compile time sake (e.g no `ENCHANTUM_ALL_ENUMS_ARE_CONTIGUOUS_OPTIMIZATION` flag which would disable support for sparse enums)\n- Allows specifying ranges for specific enums when needed\n- Compiles fast.\n- Clean and Simple Functor based API `enchantum::to_string(E)` no `enchantum::to_string\u003cE::V\u003e()` since compile times are fast.\n- Features like disabling null termination if not needed and specifying common enum prefix for C style enums, and reflect '0' values for bit flag enums.\n- Supports all sort of enums (scoped,unscoped,C style unfixed underlying type,anonymous namespaced enums, enums with commas in their typename,etc...);\n- Efficient object binary size and executable size.\n\n**Cons**\n- C++20 required\n- Compiler errors are incomprehensible if something goes wrong, needs a level 10 wizard to read them.\n- No support for wide strings (yet)\n---\n\n## Benchmarks\n\nEach compile time benchmark was run 10 times and averaged unless noted otherwise.\n`range` is `ENCHANTUM_MAX_RANGE` and `MAGIC_ENUM_RANGE_MAX`, for `simple_enum` it is defining `last` and `first` with the range because I could not find a macro for this, this is technically misuse of the library since it likes having these values close to the actual range but the comparisons would be unfair.\n\nThe enum members are from 0 to Count\n\n\n| Test Case       | Small      | Big          | Large Range | Ideal Range |\n|-----------------|------------|--------------|-------------|-------------|\n| Number of Enums | 200        | 32           | 200         | 100         |\n| Enum Range      | (-128,128) | (-256,256)   | (-1024,1024)| (0,50)      |\n| Values per Enum | 16         | 200          | 16          |  50         |\n\n\n### Compile Time\nAll times in **seconds** (lower is better). Compiled with `-O3` fir GCC and Clang while `/Ox` for MSVC. \n\n**Note**: \"Timeout\" means it took more than 20 minutes and still did not finish\n\n| Compiler    | Test Case   | `enchantum`  | `magic_enum` | `simple_enum` |\n|-------------|-------------|--------------| ------------ |---------------|\n| **GCC**     | Small       | 6.1          |  47          | 21.5          |\n|             | Big         | 4.5          |  21          | 6.3           |\n|             | Large Range | 26.7         |  Timeout     | 313           |\n|             | Ideal Range | 3            |  8.1         | 2.7           |\n|                                                                         |\n| **Clang**   | Small       | 6.2          |  47          | 14            |\n|             | Big         | 3.5          |  18          | 4.4           |\n|             | Large Range | 22.3         |  Timeout     | 96.3          |\n|             | Ideal Range | 3            |  8.7         | 2.3           |\n|                                                                         |\n| **MSVC**    | Small       | 15.8         |  80          | 186           |\n|             | Big         | 8.8          |  37          | 32.1          |\n|             | Large Range | 85.3         |  Timeout     | Timeout       |\n|             | Ideal Range | 5.8          |  17.9        | 4.7           |\n\n\n## Object File Sizes\n\nLower is better\n\n[A simple godbolt link for magic_enum vs enchantum](https://godbolt.org/#g:!((g:!((h:output,i:(editorid:1,fontScale:14,fontUsePx:'0',j:1,wrap:'1'),l:'5',n:'0',o:'Output+of+x86-64+clang+(trunk)+(Compiler+%231)',t:'0'),(h:compiler,i:(compiler:clang_trunk,filters:(b:'0',binary:'1',binaryObject:'1',commentOnly:'0',debugCalls:'1',demangle:'0',directives:'0',execute:'1',intel:'0',libraryCode:'0',trim:'1',verboseDemangling:'0'),flagsViewOpen:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,libs:!(),options:'-O3+-DENCH%3D0+-std%3Dc%2B%2B20',overrides:!(),selection:(endColumn:1,endLineNumber:1,positionColumn:1,positionLineNumber:1,selectionStartColumn:1,selectionStartLineNumber:1,startColumn:1,startLineNumber:1),source:1),l:'5',n:'0',o:'+x86-64+clang+(trunk)+(Editor+%231)',t:'0'),(h:codeEditor,i:(filename:'1',fontScale:14,fontUsePx:'0',j:1,lang:c%2B%2B,selection:(endColumn:1,endLineNumber:16,positionColumn:1,positionLineNumber:16,selectionStartColumn:1,selectionStartLineNumber:16,startColumn:1,startLineNumber:16),source:'%23if+ENCH%0A%23include+%3Chttps://raw.githubusercontent.com/ZXShady/enchantum/refs/heads/main/single_include/enchantum_single_header.hpp%3E%0A%23define+magic_enum+enchantum%0A%23define+enum_name+to_string%0A%23else%0A%23define+MAGIC_ENUM_RANGE_MIN+-500%0A%23define+MAGIC_ENUM_RANGE_MAX+500%0A%23include+%3Chttps://raw.githubusercontent.com/Neargye/magic_enum/refs/heads/master/include/magic_enum/magic_enum.hpp%3E%0A%23endif%0Aenum+class+A+%7Balong,b,c,e,d,f,glong%7D%3B%0Aextern+A+enm%3B%0A%0Aint+main()+%7B%0A++++return+magic_enum::enum_name(enm).size()%3B%0A%7D%0A'),l:'5',n:'0',o:'C%2B%2B+source+%231',t:'0')),header:(),l:'4',m:100,n:'0',o:'',s:2,t:'0')),version:4)\n\nClang is only currently measured. But GCC produced same sizes almost\n\n\n| Compiler    | Test Case   | `enchantum`  | `magic_enum` | `simple_enum` |\n|-------------|-------------|--------------| ------------ |---------------|\n| **Clang**   | Small       | 447  KB      |  1132 KB     |  3773  KB     |\n|             | Big         | 249  KB      |  1368 KB     | ~12000 KB     |\n|             | Large Range | 504  KB      |  Unknown     | ~96000 KB     |\n|             | Ideal Range | 465  KB      |  1091 KB     |  1253 KB      |\n\n**Note**:\nThe reason `simple_enum` is so big in object sizes is that it generates a huge table of all strings it does not do string optimizations like `enchantum` or `magic_enum` which leads to big object sizes there are a lot of useless strings in the binary but it also allows the library to do `O(1)` enum to string lookup for **any** enum, which I don't necessarily think is worth it and compile faster.\n\n\n### Executable Sizes\n\nCompiled the object files into their own executable then ran `strip` over them.\n\n| Compiler    | Test Case   | `enchantum`  | `magic_enum` | `simple_enum` |\n|-------------|-------------|--------------| ------------ |---------------|\n| **Clang**   | Small       | 106  KB      |  106 KB      |  2996   KB    |\n|             | Big         | 182  KB      |  182  KB     |  959    KB    |\n|             | Large Range | 106  KB      |  Unknown     |  ~23000 KB    |\n|             | Ideal Range | 147  KB      |  147 KB      |  323    KB    |\n\n**Remarks**: although magic enum did not compile in the large range test, the executable size is expected to be the same as enchantum given it optimizes strings.\n\n\n---\n\n## Summary\n\n**enchantum** significantly reduces compile times and object sizes in enum reflection projects. In my own project (which uses [libassert](https://github.com/jeremy-rifkin/libassert) and enum reflection for configuration), switching from `magic_enum` reduced full rebuild times from about 2 minutes to 1 minute and 26 seconds. I was surprised that `magic_enum` alone took 34 seconds.\n\nI also tried compiling my project using -2048,2048 as my range and it took 1 minute and 46 seconds! that's still less than `magic_enum` by default while having **16x** the default range.\n\n\nThe trade-off is that `enchantum` requires C++20, while `magic_enum` supports C++17.\nBut this requirement can be lifted if there is enough demand for a C++17 version of `enchantum`.\n\n\n# CMake Integration\n\nThe **cmake** file provides the target `enchantum::enchantum` since this library is header-only it is very simple to use you can copy and paste the files and add the include directory or use **cmake** and the library as a submodule. \n\n```cpp\nadd_subdirectory(\"third_party/enchantum\")\ntarget_link_libraries(your_executable enchantum::enchantum)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzxshady%2Fenchantum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzxshady%2Fenchantum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzxshady%2Fenchantum/lists"}