jh::meta::lookup_map< K, V, N, Hash > Struct Template Reference

Fixed-capacity hash-based flat map providing switch-like lookup semantics. More...

#include <jh/metax/lookup_map.h>

Classes
struct	entry
	Single entry stored in the lookup table. More...

Public Types
using	container_type
	Storage type selected based on POD suitability.

Public Member Functions
template<typename Arr>
constexpr	lookup_map (Arr &&init, V default_val={}, Hash hasher={})
	Construct from an array of std::pair<K,V>.
template<typename KeyIn>
constexpr const V &	operator[] (KeyIn &&key_in) const noexcept
	Lookup operator using transparent key conversion.

Public Attributes
container_type	entries
	Sorted entries.
V	default_value
	Value returned when key not found.

Static Public Attributes
static constexpr std::size_t	entry_size = sizeof(entry)
static constexpr std::size_t	total_size = entry_size * N

Detailed Description

template<typename K, typename V, std::size_t N, typename Hash>
requires requires(K k) { { Hash{}(k) } -> std::convertible_to<std::size_t>; }
struct jh::meta::lookup_map< K, V, N, Hash >

Fixed-capacity hash-based flat map providing switch-like lookup semantics.

Provides a switch-style lookup mechanism for types supporting hashing and equality. Designed to deliver predictable performance across constexpr and runtime paths.

Design motivations

• The lookup cost is O(log(N)), based on binary search over precomputed hashes.
• For small N, the dominant cost is computing the hash. If a type would require hashing before participating in a switch-like dispatch, the total cost closely matches a switch under small-table conditions.
• For large N, both this structure and a compiler-lowered switch typically operate in O(log(N)), so asymptotic behavior does not differ significantly.
• Poor hash quality is tolerated: the structure remains correct and performance degrades safely toward O(N).
• Hash collisions are resolved by short linear scans inside the equal-hash range.
• The structure generalizes switch semantics to types that are not natively switchable, capturing the complete hash-then-dispatch pattern while ensuring deterministic layout and constexpr capability.

Transparent lookup behavior

• Transparent operator[] queries are enabled through jh::meta::extension::key_traits<K>, which defines how an apparent input type KeyIn is converted into the canonical key type K.
• This conversion is explicit: a canonical K object will be constructed from the apparent input. Therefore K is expected to be lightweight, such as a POD key or a full-lifetime literal-based string view ("..."_psv).
• This differs from heterogeneous lookup in unordered_map; the goal here is predictable constexpr behavior, not amortized dynamic optimization.

Implementation

1. Entries are pre-hashed using Hash and stored as a fixed-size array.
2. The array is sorted by hash, enabling binary search on the hash field.
3. Equal-hash entries are resolved by a short linear comparison scan.
4. Construction uses constexpr sorting when evaluated at compile time and runtime sorting otherwise.
5. The container uses no dynamic allocation and provides deterministic layout.

Template Parameters

K	Canonical key type stored in the map.
V	Value type associated with each key.
N	Number of stored entries.
Hash	Hash functor producing std::size_t.

Note

Prefer compile-time construction with lightweight POD keys or full-lifetime string-view literals (e.g. "..."_psv) to ensure zero-overhead canonical conversions through key_traits.

Member Typedef Documentation

container_type

template<typename K, typename V, std::size_t N, typename Hash>

using jh::meta::lookup_map< K, V, N, Hash >::container_type

Initial value:

decltype([]() {
           if constexpr (jh::pod::pod_like<entry> && (total_size <= jh::pod::max_pod_array_bytes))
               return std::type_identity<jh::pod::array<entry, N>>{};
           else
               return std::type_identity<std::array<entry, N>>{};
       }())::type

Storage type selected based on POD suitability.

If entry is POD-like and the total size does not exceed jh::pod::max_pod_array_bytes, jh::pod::array<entry, N> is used; otherwise std::array<entry, N> is selected.
Using the POD variant enables placement in read-only segments.

Constructor & Destructor Documentation

lookup_map()

template<typename K, typename V, std::size_t N, typename Hash>

template<typename Arr>

jh::meta::lookup_map< K, V, N, Hash >::lookup_map ( Arr && init, V default_val = {}, Hash hasher = {} )

inlineexplicitconstexpr

Construct from an array of std::pair<K,V>.

Computes hashes, stores entries and sorts them by hash. Performs constexpr or runtime sorting depending on evaluation context.

Parameters

init	Array of key-value pairs.
default_val	Value returned when lookup fails.
hasher	Hash functor.

Member Function Documentation

operator[]()

template<typename K, typename V, std::size_t N, typename Hash>

template<typename KeyIn>

const V & jh::meta::lookup_map< K, V, N, Hash >::operator[] ( KeyIn && key_in ) const

inlineconstexprnoexcept

Lookup operator using transparent key conversion.

Template Parameters

KeyIn

Input key type convertible via key_traits<K>.

Parameters

key_in

Key to query.

Returns

Reference to the stored value or default_value if not found.

---

The documentation for this struct was generated from the following file:

• include/jh/metax/lookup_map.h