Hash map with small buffer optimization for stack-allocated storage. More...

#include <nfx/containers/StackHashMap.h>

Public Types
using	key_type = TKey
	Type alias for key type.
using	mapped_type = TValue
	Type alias for mapped value type.
using	value_type = std::pair<const TKey, TValue>
	Type alias for key-value pair type.
using	size_type = size_t
	Type alias for size type.
using	difference_type = std::ptrdiff_t
	Type alias for difference type.
using	key_equal = KeyEqual
	Type alias for key equality comparator.

Public Member Functions
	StackHashMap ()
	Default constructor with empty stack storage.
	StackHashMap (std::initializer_list< std::pair< TKey, TValue > > init)
	Construct map from initializer_list.
template<typename InputIt>
	StackHashMap (InputIt first, InputIt last)
	Construct map from iterator range.
bool	isEmpty () const noexcept
	Check if the map is empty.
size_t	size () const noexcept
	Get the number of elements in the map.
TValue &	at (const TKey &key)
	Checked element access with bounds checking.
const TValue &	at (const TKey &key) const
	Checked const element access with bounds checking.
TValue &	operator[] (const TKey &key)
	STL-compatible subscript operator (insert-if-missing).
TValue &	operator[] (TKey &&key)
	STL-compatible subscript operator with move semantics.
std::pair< value_type *, bool >	insert (const std::pair< TKey, TValue > &value)
	Insert a key-value pair (copy semantics).
std::pair< value_type *, bool >	insert (std::pair< TKey, TValue > &&value)
	Insert a key-value pair (move semantics).
template<typename... Args>
std::pair< value_type *, bool >	emplace (Args &&... args)
	Emplace a key-value pair with in-place construction.
void	insertOrAssign (const TKey &key, const TValue &value)
	Insert or assign a key-value pair (copy value).
void	insertOrAssign (const TKey &key, TValue &&value)
	Insert or assign a key-value pair (move value).
void	insertOrAssign (TKey &&key, TValue &&value)
	Insert or assign a key-value pair (move key and value).
size_t	erase (const TKey &key)
	Erase element by key.
void	clear () noexcept
	Clear all elements from the map.
std::optional< std::pair< TKey, TValue > >	extract (const TKey &key)
	Extract a key-value pair from the map without destroying it.
void	merge (StackHashMap &other)
	Merge another StackHashMap into this one.
void	merge (StackHashMap &&other)
	Merge another StackHashMap into this one (rvalue overload).
TValue *	find (const TKey &key) noexcept
	Find a value by key.
const TValue *	find (const TKey &key) const noexcept
	Find a value by key (const version).
size_t	count (const TKey &key) const
	Count occurrences of key in map.
bool	contains (const TKey &key) const
	Check if a key exists in the map.
template<typename K> requires requires( KeyEqual eq, const K& k, const TKey& t ) { eq( k, t ); }
bool	contains (const K &key) const
	Check if a key exists in the map (heterogeneous lookup).
template<typename Func>
void	forEach (Func &&func)
	Apply a function to each key-value pair.
template<typename Func>
void	forEach (Func &&func) const
	Apply a function to each key-value pair (const version).

Static Public Member Functions
static constexpr size_t	stackCapacity () noexcept
	Get the maximum stack capacity before heap allocation.

Detailed Description

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>
class nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >

Hash map with small buffer optimization for stack-allocated storage.

Template Parameters

TKey	Key type (supports heterogeneous lookup for compatible types)
TValue	Value type
N	Maximum stack capacity before heap allocation (default: 8)
KeyEqual	Key equality comparator (default: std::equal_to<> for transparent comparison)

StackHashMap uses a hybrid storage strategy:

Small capacity (≤N): Linear search in stack-allocated array (cache-friendly, zero heap allocations)
Large capacity (>N): Automatic transition to FastHashMap (Robin Hood hashing on heap)

This is ideal for small maps (config options, local caches) where heap allocation overhead would dominate performance. The transition to heap is transparent and automatic.

Definition at line 68 of file StackHashMap.h.

Member Typedef Documentation

◆ difference_type

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

using nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::difference_type = std::ptrdiff_t

Type alias for difference type.

Definition at line 88 of file StackHashMap.h.

◆ key_equal

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

using nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::key_equal = KeyEqual

Type alias for key equality comparator.

Definition at line 91 of file StackHashMap.h.

◆ key_type

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

using nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::key_type = TKey

Type alias for key type.

Definition at line 76 of file StackHashMap.h.

◆ mapped_type

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

using nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::mapped_type = TValue

Type alias for mapped value type.

Definition at line 79 of file StackHashMap.h.

◆ size_type

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

using nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::size_type = size_t

Type alias for size type.

Definition at line 85 of file StackHashMap.h.

◆ value_type

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

using nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::value_type = std::pair<const TKey, TValue>

Type alias for key-value pair type.

Definition at line 82 of file StackHashMap.h.

Constructor & Destructor Documentation

◆ StackHashMap() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::StackHashMap ( std::initializer_list< std::pair< TKey, TValue > > init )

inline

Construct map from initializer_list.

Parameters

init	Initializer list of key/value pairs

◆ StackHashMap() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

template<typename InputIt>

nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::StackHashMap	(	InputIt	first,
		InputIt	last )

inline

Construct map from iterator range.

Template Parameters

InputIt Input iterator type (must dereference to std::pair-like type)

Parameters

first	Beginning of range to copy from
last	End of range (exclusive)

Member Function Documentation

◆ at() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

TValue & nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::at ( const TKey & key )

inline

Checked element access with bounds checking.

Parameters

key	The key to access

Returns: Reference to the value associated with the key

Exceptions

std::out_of_range if key is not found

◆ at() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

const TValue & nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::at ( const TKey & key ) const

inline

Checked const element access with bounds checking.

Parameters

key	The key to access

Returns: Const reference to the value associated with the key

Exceptions

std::out_of_range if key is not found

◆ clear()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::clear ( )

inlinenoexcept

Clear all elements from the map.

Clears stack storage or heap storage, does not deallocate heap map

◆ contains() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

template<typename K>
requires requires( KeyEqual eq, const K& k, const TKey& t ) { eq( k, t ); }

bool nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::contains ( const K & key ) const

inlinenodiscard

Check if a key exists in the map (heterogeneous lookup).

Template Parameters

K	Key type (supports heterogeneous lookup for compatible types)

Parameters

key	The key to search for

Returns: true if key exists, false otherwise

Note: This function is marked [[nodiscard]] - the return value should not be ignored; Enabled only if KeyEqual supports comparing K with TKey

◆ contains() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

bool nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::contains ( const TKey & key ) const

inlinenodiscard

Check if a key exists in the map.

Parameters

key	The key to search for

Returns: true if key exists, false otherwise

Note: This function is marked [[nodiscard]] - the return value should not be ignored

◆ count()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

size_t nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::count ( const TKey & key ) const

inlinenodiscard

Count occurrences of key in map.

Parameters

key	The key to search for

Returns: 1 if key exists, 0 otherwise (maps have unique keys)

Note: This function is marked [[nodiscard]] - the return value should not be ignored

◆ emplace()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

template<typename... Args>

std::pair< value_type *, bool > nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::emplace ( Args &&... args )

inline

Emplace a key-value pair with in-place construction.

Template Parameters

Args	Argument types for constructing the pair

Parameters

args	Arguments forwarded to construct the pair

Returns: Pair of pointer to element and bool indicating insertion success

◆ erase()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

size_t nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::erase ( const TKey & key )

inline

Erase element by key.

Parameters

key	The key to erase

Returns: Number of elements erased (0 or 1)

◆ extract()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

std::optional< std::pair< TKey, TValue > > nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::extract ( const TKey & key )

inlinenodiscard

Extract a key-value pair from the map without destroying it.

Parameters

key	The key to extract

Returns: std::optional containing the extracted key-value pair if found, std::nullopt otherwise

Removes the element from the map and returns the key-value pair. If the key is not found, returns std::nullopt.

Note: This function is marked [[nodiscard]] - the return value should not be ignored

◆ find() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

const TValue * nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::find ( const TKey & key ) const

inlinenodiscardnoexcept

Find a value by key (const version).

Parameters

key	The key to search for

Returns: Const pointer to the value if found, nullptr otherwise

Note: This function is marked [[nodiscard]] - the return value should not be ignored

◆ find() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

TValue * nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::find ( const TKey & key )

inlinenodiscardnoexcept

Find a value by key.

Parameters

key	The key to search for

Returns: Pointer to the value if found, nullptr otherwise

Note: This function is marked [[nodiscard]] - the return value should not be ignored

◆ forEach() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

template<typename Func>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::forEach ( Func && func )

inline

Apply a function to each key-value pair.

Template Parameters

Func	Function type with signature void(const TKey&, TValue&) or compatible

Parameters

func	Function to apply to each element

Iterates over all elements in unspecified order. For stack storage, iteration order matches insertion order (up to N elements). For heap storage, iteration order is unspecified (hash table order).

◆ forEach() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

template<typename Func>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::forEach ( Func && func ) const

inline

Apply a function to each key-value pair (const version).

Template Parameters

Func	Function type with signature void(const TKey&, const TValue&) or compatible

Parameters

func	Function to apply to each element

Iterates over all elements in unspecified order. For stack storage, iteration order matches insertion order (up to N elements). For heap storage, iteration order is unspecified (hash table order).

◆ insert() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

std::pair< value_type *, bool > nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::insert ( const std::pair< TKey, TValue > & value )

inline

Insert a key-value pair (copy semantics).

Parameters

value The key-value pair to insert

Returns: Pair of pointer to element and bool indicating insertion success

If key already exists, returns pointer to existing element and false. Otherwise inserts new element and returns pointer with true. May trigger transition to heap storage.

◆ insert() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

std::pair< value_type *, bool > nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::insert ( std::pair< TKey, TValue > && value )

inline

Insert a key-value pair (move semantics).

Parameters

value The key-value pair to insert (moved)

Returns: Pair of pointer to element and bool indicating insertion success

If key already exists, returns pointer to existing element and false. Otherwise inserts new element and returns pointer with true. May trigger transition to heap storage.

◆ insertOrAssign() [1/3]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::insertOrAssign	(	const TKey &	key,
		const TValue &	value )

inline

Insert or assign a key-value pair (copy value).

Parameters

key	The key to insert or assign to
value	The value to assign

If key exists, assigns new value. Otherwise inserts new pair. May trigger transition to heap storage.

◆ insertOrAssign() [2/3]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::insertOrAssign	(	const TKey &	key,
		TValue &&	value )

inline

Insert or assign a key-value pair (move value).

Parameters

key	The key to insert or assign to
value	The value to assign (moved)

If key exists, assigns new value. Otherwise inserts new pair. May trigger transition to heap storage.

◆ insertOrAssign() [3/3]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::insertOrAssign	(	TKey &&	key,
		TValue &&	value )

inline

Insert or assign a key-value pair (move key and value).

Parameters

key	The key to insert or assign to (moved)
value	The value to assign (moved)

If key exists, assigns new value. Otherwise inserts new pair. May trigger transition to heap storage.

◆ isEmpty()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

bool nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::isEmpty ( ) const

inlinenodiscardnoexcept

Check if the map is empty.

Returns: true if size() == 0, false otherwise

Note: This function is marked [[nodiscard]] - the return value should not be ignored

◆ merge() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::merge ( StackHashMap< TKey, TValue, N, KeyEqual > && other )

inline

Merge another StackHashMap into this one (rvalue overload).

Parameters

other The map to merge from (elements are moved)

Same as merge(StackHashMap&) but accepts rvalue references.

◆ merge() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

void nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::merge ( StackHashMap< TKey, TValue, N, KeyEqual > & other )

inline

Merge another StackHashMap into this one.

Parameters

other The map to merge from (elements are moved, not copied)

Attempts to insert each element from other into this map. Elements that already exist in this map are left in other. After the operation, other contains only elements that were not inserted.

◆ operator[]() [1/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

TValue & nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::operator[] ( const TKey & key )

inline

STL-compatible subscript operator (insert-if-missing).

Parameters

key	The key to access or insert

Returns: Reference to the value associated with the key

If key doesn't exist, inserts default-constructed value. Requires TValue to be default-constructible. May trigger transition to heap storage if stack capacity exceeded.

Note: This function is NOT marked noexcept as it may insert/resize

◆ operator[]() [2/2]

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

TValue & nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::operator[] ( TKey && key )

inline

STL-compatible subscript operator with move semantics.

Parameters

key	The key to access or insert (moved if new)

Returns: Reference to the value associated with the key

If key doesn't exist, inserts default-constructed value. Requires TValue to be default-constructible. May trigger transition to heap storage if stack capacity exceeded.

Note: This function is NOT marked noexcept as it may insert/resize

◆ size()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

size_t nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::size ( ) const

inlinenodiscardnoexcept

Get the number of elements in the map.

Returns: Current number of key-value pairs stored

Note: This function is marked [[nodiscard]] - the return value should not be ignored

◆ stackCapacity()

template<typename TKey, typename TValue, size_t N = 8, typename KeyEqual = std::equal_to<>>

constexpr size_t nfx::containers::StackHashMap< TKey, TValue, N, KeyEqual >::stackCapacity ( )

inlinestaticnodiscardconstexprnoexcept

Get the maximum stack capacity before heap allocation.

Returns: Stack capacity (template parameter N)

Note: This function is marked [[nodiscard]] - the return value should not be ignored

Definition at line 140 of file StackHashMap.h.

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

StackHashMap.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ difference_type

◆ key_equal

◆ key_type

◆ mapped_type

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ StackHashMap() [1/2]

◆ StackHashMap() [2/2]

Member Function Documentation

◆ at() [1/2]

◆ at() [2/2]

◆ clear()

◆ contains() [1/2]

◆ contains() [2/2]

◆ count()

◆ emplace()

◆ erase()

◆ extract()

◆ find() [1/2]

◆ find() [2/2]

◆ forEach() [1/2]

◆ forEach() [2/2]

◆ insert() [1/2]

◆ insert() [2/2]

◆ insertOrAssign() [1/3]

◆ insertOrAssign() [2/3]

◆ insertOrAssign() [3/3]

◆ isEmpty()

◆ merge() [1/2]

◆ merge() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ size()

◆ stackCapacity()