eternal.hpp is a header-only C++ implementation of constexpr/compile-time maps and hash maps. It provides an API that is somewhat compatible with std::map/std::unordered_map, but doesn't support insertion, or other modifications. It's main focus is in binary size: it generates minimal code and doesn't incur any static initialization overhead.
Why is this useful?
- Lookup tables
Tested with these compilers/platforms:
- Linux GCC 4.9.4 (runtime only, since
constexprsupport is broken in this version) - Linux GCC 5.5
- Linux GCC 6.5
- Linux GCC 7.3
- Linux GCC 8.1
- Linux Clang 3.9.1
- Linux Clang 4
- Linux Clang 5
- Linux Clang 6
- Linux Clang 7
- macOS Xcode 10.1
- Android NDK r17+
Usage
MAPBOX_ETERNAL_CONSTEXPR const auto colors = mapbox::eternal::map<mapbox::eternal::string, Color>({
{ "red", { 255, 0, 0, 1 } },
{ "green", { 0, 128, 0, 1 } },
{ "yellow", { 255, 255, 0, 1 } },
{ "white", { 255, 255, 255, 1 } },
{ "black", { 0, 0, 0, 1 } }
});mapbox::eternal::map<key, value>()is a factory function that produces aconstexprmap from thestd::pair<key, value>s passed to it.- Alternatively, use
mapbox::eternal::hash_map<key, value>()to construct a hash map. Thekeyneeds a specialization ofstd::hash. - Use
mapbox::eternal::stringforconstexprstrings. - If you need to support GCC 4.9, use
MAPBOX_ETERNAL_CONSTEXPRinstead ofconstexprin the variable definition. - You can pass the elements in arbitrary order; they will be sorted at compile time (except for GCC 4.9). To speed up compilation, list the elements in sorted order. To determine the sort order for
hash_map, iterate over the map and print the result. Note that hashes may be architecture-specific. - Both
map()andhash_map()support multiple values for the same key. To ensure that keys are unique, runstatic_assert(map.unique());(or equivalent for GCC 4.9) - The preprocessor variable
MAPBOX_ETERNAL_IS_CONSTEXPRis set to1ifconstexprconstruction and lookups are supported.
Performance
Uses a list of 148 unique CSS color names
Run on (8 X 2600 MHz CPU s)
CPU Caches:
L1 Data 32K (x4)
L1 Instruction 32K (x4)
L2 Unified 262K (x4)
L3 Unified 6291K (x1)
-----------------------------------------------------------------------------
Benchmark Time CPU Iterations
-----------------------------------------------------------------------------
EternalMap_ConstexprLookup 2 ns 2 ns 424582090
EternalMap_Lookup 48 ns 48 ns 14494194
EternalMap_LookupMissing 35 ns 35 ns 20442492
EternalMap_LookupEqualRange 78 ns 78 ns 8862891
EternalHashMap_ConstexprLookup 2 ns 2 ns 429076688
EternalHashMap_Lookup 30 ns 30 ns 22685952
EternalHashMap_LookupMissing 17 ns 17 ns 39521898
EternalHashMap_LookupEqualRange 43 ns 43 ns 16696442
StdMap_Lookup 51 ns 50 ns 13580630
StdMap_LookupMissing 58 ns 58 ns 11868028
StdMap_LookupEqualRange 89 ns 89 ns 7766129
StdMultimap_Lookup 50 ns 50 ns 14262312
StdMultimap_LookupMissing 60 ns 59 ns 11555922
StdMultimap_LookupEqualRange 103 ns 103 ns 6783077
StdUnorderedMap_Lookup 43 ns 43 ns 16175696
StdUnorderedMap_LookupMissing 50 ns 50 ns 10000000
StdUnorderedMap_LookupEqualRange 57 ns 57 ns 12256189
StdUnorderedMultimap_Lookup 43 ns 43 ns 16011528
StdUnorderedMultimap_LookupMissing 52 ns 51 ns 10000000
StdUnorderedMultimap_LookupEqualRange 61 ns 60 ns 11519221