https://github.com/ZXShady/enchantum
Faster enum reflection for C++17 since I don't want to wait for C++26 reflection.
https://github.com/ZXShady/enchantum
c-plus-plus cpp cpp17 cpp20 enum enum-to-string header-only is-bitflag-enum metaprogramming no-dependencies reflection reflection-library serialization string-to-enum templates
Last synced: 9 days ago
JSON representation
Faster enum reflection for C++17 since I don't want to wait for C++26 reflection.
- Host: GitHub
- URL: https://github.com/ZXShady/enchantum
- Owner: ZXShady
- License: mit
- Created: 2025-04-17T03:16:02.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-24T21:13:30.000Z (19 days ago)
- Last Synced: 2026-04-24T23:20:16.275Z (19 days ago)
- Topics: c-plus-plus, cpp, cpp17, cpp20, enum, enum-to-string, header-only, is-bitflag-enum, metaprogramming, no-dependencies, reflection, reflection-library, serialization, string-to-enum, templates
- Language: C++
- Homepage:
- Size: 525 KB
- Stars: 122
- Watchers: 4
- Forks: 11
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cpp-with-stars - Enchantum - only library for compile-time enum reflection. [MIT] | 2026-04-24 | (Reflection)
- fucking-awesome-cpp - Enchantum - modern C++17 header-only library for compile-time enum reflection. [MIT] (Reflection)
- awesome-cpp - Enchantum - modern C++17 header-only library for compile-time enum reflection. [MIT] (Reflection)
README
# Enchantum
**Enchantum** (short for "enchant enum") is a modern **C++17** header-only library for **compile-time enum reflection**. It provides fast, lightweight access to enum values, names, and bitflags all without macros or boilerplate.
> Every year, countless turtles perish due to the pollution caused by slow, bloated build times.
Save the turtles — and your compile times — by switching to enchantum!
Source: I made it up.
Key Features
- Macro-free and non-intrusive boilerplate-free reflection
- Fast compile times (benchmarked below)
- Most efficient binary size wise.
- 0 Allocations
- Supports:
- Scoped enums
- Unscoped C enums
- Sparse enums
- Bitflags
- Iteration over values,names and `[enum, name]` pairs.
- `string <=> enum` conversions
- `enum <=> index` conversions
- enum validation functions like `cast` and `contains`
- enum aware containers adaptors like `enchantum::bitset` and `enchantum::array`
- Extra features like:
- Functions that output enums with their scope
- Optional null terminator disabling
- Optional prefix stripping for C-style enums
- `0` values are reflected for bitflag enums
[Simple Examples](#simple-examples)
[Why another enum reflection library?](#why-another-enum-reflection-library)
[Features](docs/features.md)
[Benchmarks](#benchmarks)
[Limitations](docs/limitations.md)
[CMake Integration](#cmake-integration)
Tested locally on Windows 10 with:
- Visual Studio 2022 (19.44)
- GCC 14.2.0
- Clang 20.1.2
Compiler Support: (Look at [CI](https://github.com/ZXShady/enchantum/actions))
- GCC >= 9
- Clang >= 8
- MSVC >= 19.24 VS16.4 (lower verions tested through godbolt)
- Resharper >= 2023
Tested through basic tests on godbolt since I could not install it on CI, so support for them may not be the best.
- ICX >= 2021.1.2 (Tested through godbolt [test link](https://godbolt.org/z/5naTha56K))
- NVC++ >= 22.7 (minimum on godbolt [test link](https://godbolt.org/z/xr7xr6Y6v))
---
> [!IMPORTANT]
> Be sure to read [Limitations](docs/limitations.md) before using enchantum.
## Simple Examples
* to string
```cpp
#include // to_string
#include // iostream support
enum class Music { Rock, Jazz , Metal };
int main()
{
auto music = Music::Rock;
std::string_view music_name = enchantum::to_string(music);
// music_name == "Rock"
using namespace enchantum::iostream_operators;
std::cout << music;
// Prints Rock
}
```
* from strings
```cpp
#include // cast
enum class Music { Rock, Jazz , Metal };
int main()
{
// case sensitive
std::optional music = enchantum::cast("Jazz");
if(music.has_value()) // check if cast succeeded
{
// *music == Music::Jazz
}
// pass a predicate taking two string views
music = enchantum::cast("JAZZ",[](char x,char y){
using UC = unsigned char;
return std::tolower(UC(x)) == std::tolower(UC(y));
});
if(music.has_value()) {
// *music == Music::Jazz
}
}
```
* index into enums
```cpp
#include // index_to_enum and enum_to_index
enum class Music { Rock, Jazz , Metal };
int main()
{
// case sensitive
std::optional music = enchantum::index_to_enum(1); // Jazz is the second enum member
if(music.has_value()) // check if index is not out of bounds
{
// *music == Music::Jazz
std::optional index = enchantum::enum_to_index(*music);
// *index == 1
}
}
```
* iteration
```cpp
#include // entries,values and names
enum class Music { Rock, Jazz , Metal };
int main()
{
// Iterate over values
for(Music music : enchantum::values_generator)
std::cout << static_cast(music) << " ";
// Prints "0 1 2"
// Iterate over names
for(std::string_view name : enchantum::names_generator)
std::cout << name << " ";
// Prints "Rock Jazz Metal"
// Iterate over both!
for(const auto [music,name] : enchantum::entries_generator)
std::cout << name << " = " << static_cast(music) << "\n";
// Prints
// Rock = 0
// Jazz = 1
// Metal = 2
}
```
Look at [Features](docs/features.md) for more information.
## Why Another Enum Reflection Library?
There 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)?
### magic_enum
**Pros**
- Macro-free (non intrusive).
- No modifications needed for existing enums.
- Allows specifying ranges for specific enums when needed.
- Supports C++17.
- Nicer compiler errors.
- Supports wide strings.
- Efficient executable binary size.
- Null terminated strings.
- 0 Allocations
**Cons**
- Compile times grow significantly with larger `MAGIC_ENUM_MAX_RANGE`.
- No warnings for not fully reflected enums.
### conjure_enum
**Pros**
- Macro-free (non intrusive)
- Uses C++20
**Cons**
- Slow compilation speed
- Bigger executable sizes
- Non optimal algorithms
- Allocations
- No warnings for not fully reflected enums.
### simple_enum
**Pros**
- Faster compile times.
- Functor based API.
- 0 Allocations
**Cons**
- Requires specifying enum `first`/`last` values manually (intrusive, doesn't work well with third-party enums)
- Compile time slows down with large enum ranges
- Big binary size bloat.
- No support for bitflags yet.
- No support for null terminated strings.
- No warnings for not fully reflected enums.
### enchantum
**Pros**
- Macro-free (non intrusive)
- Allows specifying ranges for specific enums when needed
- Compiles fast.
- Supports C++17.
- Clean and Simple Functor based API `enchantum::to_string(E)` no `enchantum::to_string()` since compile times are fast.
- 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.
- Supports all sort of enums (scoped,unscoped,C style unfixed underlying type,anonymous namespaced enums, enums with commas in their typename,etc..)
- Most efficient object binary size and executable size.
- Null terminated strings.
- 0 Allocations
- Compiler errors for not fully reflected enums.
**Cons**
- No support for wide strings.
---
## Benchmarks
### Summary
**enchantum** significantly reduces compile times and binary 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 (34 seconds difference).
I 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.
Each compile time benchmark was run 10 times and averaged unless noted otherwise.
`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.
The enum members are from 0 to Count
| Test Case | Small | Big | Large Range | Ideal Range |
|------------------------|------------|--------------|-------------|-------------|
| Number of Enums | 200 | 32 | 200 | 100 |
| Enum Reflection Range | (-128,128) | (-256,256) | (-1024,1024)| (0,50) |
| Enum members from 0 to | 16 | 200 | 16 | 50 |
### Compile Time
All times in seconds (lower is better, bold is fastest). Compiled with `-O3` fir GCC and Clang while `/Ox` for MSVC.
"Timeout" means it took more than 20 minutes and still did not finish
**Notes**: numbers in `()` are with [`ENCHANTUM_CHECK_OUT_OF_BOUNDS_BY`](docs/features.md/#enchantum_check_out_of_bounds_by) set to the default which is `2`.
in short terms it is extra compile time only checks against not fully reflected enums which can be disabled by setting it to `0`.
Conjure enum was compiled with `FIX8_CONJURE_ENUM_MINIMAL` macro defined.
| Compiler | Test Case | `enchantum` | `magic_enum` | `simple_enum` | `conjure_enum` |
|-------------|-------------|-----------------|--------------|---------------|----------------|
| **GCC** | Small | **6.0** (9.3) | 47 | 21.5 | 97.1 |
| | Big | **2.7** (4.6) | 21 | 6.3 | 81.7 |
| | Large Range | **15.9** (45.1) | Timeout | 313 | Unknown |
| | Ideal Range | 3 (4.2) | 8.1 | **2.7** | 46.8 |
| | |
| **Clang** | Small | **5.8** (8.7) | 47 | 14 | 66.8 |
| | Big | **2.3** (3.6) | 18 | 4.4 | 52.9 |
| | Large Range | **15.1** (36.6) | Timeout | 96.3 | Timeout |
| | Ideal Range | 2.9 (3.5) | 8.7 | **2.3** | 32 |
| |
| **MSVC** | Small | **15.8** (50.7) | 80 | 186 | ERROR |
| | Big | **8.8** (13.6) | 37 | 32.1 | 244.9 |
| | Large Range | **85.3** (265.1)| Timeout | Timeout | Timeout |
| | Ideal Range | 5.8 (18.1) | 17.9 | **4.7** | 95.7 |
`conjure_enum` in "Small" test case caused the compiler to emit
```js
fatal error C1060: compiler is out of heap space
```
## Object File Sizes
Lower is better,bold is smallest, all measurements are in kilobytes.
[A simple godbolt link for conjure_enum vs magic_enum vs enchantum difference in binary sizes](https://godbolt.org/z/cMvdEa65d)
could not get `simple_enum` in there since it does not have a single header version.
Clang is only currently measured.
| Compiler | Test Case | `enchantum` | `magic_enum` | `simple_enum` | `conjure_enum` |
|-------------|-------------|--------------| ------------ |---------------|----------------|
| **Clang** | Small | **275** | 732 | 12070 | 779 |
| | Big | **84** | 1307 | 3847 | 1400 |
| | Large Range | **275** | Unknown | 98366 | Unknown |
| | Ideal Range | **299** | 1051 | 1233 | 1123 |
**Note**:
The 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
It stores this for example `"auto se::f() [enumeration = A_0::A_0_4]"`, the entire internal string instead of
only the part it needs (the "A_0_4" part)
and this gets worse as the main enum name gets longer (e.g by putting the enums in a namespace),
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.
As for why `conjure_enum` although based on the same `magic_enum` implementation compile slower and larger binary sizes is due to unnecessary storing of enum namespaces in the binary. instead of storing `"Value"` it will store `"Namespace::Enum::Value"`.
### Executable Sizes
Compiled the object files into their own executable.
Lower is better, bold is smallest, all measurements are in kilobytes.
| Compiler | Test Case | enchantum | magic_enum | simple_enum | `conjure_enum` |
|-------------|-------------|---------------|----------------|-----------------|----------------|
| **Clang** | Small | **40** | 95 | 2897 | 243 |
| | Big | **56** | 168 | 944 | 357 |
| | Large Range | **40** | Unknown | 23200 | Unknown |
| | Ideal Range | **46** | 134 | 308 | 305 |
---
# CMake Integration
The 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.
```cpp
add_subdirectory("third_party/enchantum")
target_link_libraries(your_executable enchantum::enchantum)
```