StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Safe::Map< K, V, Compare > Class Template Referencefinal

Ordered unique-key map stored on Base's heap. More...

#include <StormByte/safe/map.hxx>

Classes

class  value_compare
 Orders entries by key, using the map comparator. More...
class  BasicIterator
 Bidirectional cursor over Base-owned map nodes. More...
class  node_type
 Owning handle to one extracted Base node. More...
struct  insert_return_type
 Result of inserting an extracted node. More...

Public Types

using key_type = K
 Key type.
using mapped_type = V
 Mapped type.
using value_type = Pair<const K, V>
 Entry type. The key is immutable.
using key_compare = Compare
 Key ordering.
using size_type = Size
 Element count. Size, not std::size_t.
using difference_type = std::ptrdiff_t
 Iterator distance type.
using reference = value_type&
 Mutable entry reference.
using const_reference = const value_type&
 Read-only entry reference.
using iterator = BasicIterator<false>
 Mutable iterator.
using const_iterator = BasicIterator<true>
 Read-only iterator.
using reverse_iterator = std::reverse_iterator<iterator>
 Mutable reverse iterator.
using const_reverse_iterator = std::reverse_iterator<const_iterator>
 Read-only reverse iterator.
using insert_result = Pair<iterator, bool>
 Iterator to the entry and whether it was inserted.
using equal_range_result = Pair<iterator, iterator>
 Lower and upper bound.
using const_equal_range_result = Pair<const_iterator, const_iterator>
 Read-only lower and upper bound.

Public Member Functions

 Map ()
 Construct an empty map.
 Map (const Compare &compare)
 Construct an empty map with a comparator.
 Map (const Map &other)
 Copy every node into new Base blocks.
 Map (Map &&other)
 Take the tree.
STORMBYTE_FORCE_INLINE Map (const std::map< K, V, Compare > &other)
 Copy a caller-owned STL map.
STORMBYTE_FORCE_INLINE Map (std::map< K, V, Compare > &&other)
 Move elements from a caller-owned STL map and leave it empty.
template<std::ranges::input_range R>
requires std::convertible_to<std::ranges::range_reference_t<R>, value_type>
STORMBYTE_FORCE_INLINE Map (std::from_range_t, R &&range)
 Copy the entries of range.
 Map (std::initializer_list< value_type > values)
 Insert every entry of an initializer list.
 ~Map () noexcept
 Destroy every node through Base.
Map & operator= (const Map &other)
 Copy-assign.
Map & operator= (Map &&other) noexcept
 Move-assign.
STORMBYTE_FORCE_INLINE Map & operator= (const std::map< K, V, Compare > &other)
 Copy-assign a caller-owned STL map.
STORMBYTE_FORCE_INLINE Map & operator= (std::map< K, V, Compare > &&other)
 Move-assign elements from a caller-owned STL map and leave it empty.
Map & operator= (std::initializer_list< value_type > values)
 Replace the contents with an initializer list.
key_compare key_comp () const
 Return the key ordering.
value_compare value_comp () const
 Return an entry comparator that uses the key ordering.
iterator begin () noexcept
 Return a mutable iterator to the first entry.
iterator end () noexcept
 Return the mutable end iterator.
const_iterator begin () const noexcept
 Return a read-only iterator to the first entry.
const_iterator end () const noexcept
 Return the read-only end iterator.
const_iterator cbegin () const noexcept
 Return a read-only iterator to the first entry.
const_iterator cend () const noexcept
 Return the read-only end iterator.
reverse_iterator rbegin () noexcept
 Return a reverse iterator to the last entry.
reverse_iterator rend () noexcept
 Return the reverse end iterator.
const_reverse_iterator rbegin () const noexcept
 Return a read-only reverse iterator to the last entry.
const_reverse_iterator rend () const noexcept
 Return the read-only reverse end iterator.
const_reverse_iterator crbegin () const noexcept
 Return a read-only reverse iterator to the last entry.
const_reverse_iterator crend () const noexcept
 Return the read-only reverse end iterator.
bool empty () const noexcept
 Test whether the map has no entries.
size_type size () const noexcept
 Return the entry count.
size_type max_size () const noexcept
 Return the largest representable entry count.
void clear () noexcept
 Destroy every node.
void swap (Map &other) noexcept
 Exchange trees.
insert_result insert (const value_type &entry)
 Insert a copy of an entry.
insert_result insert (value_type &&entry)
 Insert a moved entry.
iterator insert (const_iterator hint, const value_type &entry)
 Insert a copy of an entry, using hint when the neighbouring keys confirm it.
iterator insert (const_iterator hint, value_type &&entry)
 Insert a moved entry, using hint when the neighbouring keys confirm it.
template<class P>
requires Type::ConstructibleFrom<typename Map<K, V, Compare>::value_type, P> && (!Type::SameAs<std::remove_cvref_t<P>, typename Map<K, V, Compare>::value_type>)
insert_result insert (P &&entry)
 Insert an entry constructed from a compatible value.
template<class InputIt>
STORMBYTE_FORCE_INLINE void insert (InputIt first, InputIt last)
 Insert every entry in [first, last).
void insert (std::initializer_list< value_type > values)
 Insert every entry of an initializer list.
template<std::ranges::input_range R>
requires std::convertible_to<std::ranges::range_reference_t<R>, value_type>
STORMBYTE_FORCE_INLINE void insert_range (R &&range)
 Insert a copy of range.
template<class... Args>
insert_result try_emplace (const K &key, Args &&... args)
 Construct an entry in a new node if the key is absent.
template<class... Args>
insert_result try_emplace (K &&key, Args &&... args)
 Construct an entry in a new node if the key is absent.
template<class... Args>
iterator try_emplace (const_iterator hint, const K &key, Args &&... args)
 Construct an entry if the key is absent, using hint when the neighbouring keys confirm it.
template<class... Args>
iterator try_emplace (const_iterator hint, K &&key, Args &&... args)
 Construct an entry if the key is absent, using hint when the neighbouring keys confirm it.
template<class... Args>
insert_result emplace (Args &&... args)
 Construct an entry from arguments forwarded to value_type.
template<class... Args>
iterator emplace_hint (const_iterator hint, Args &&... args)
 Construct an entry from arguments, using hint when the neighbouring keys confirm it.
insert_result insert_or_assign (const K &key, const V &value)
 Insert or replace the mapped value.
insert_result insert_or_assign (const K &key, V &&value)
 Insert or replace the mapped value.
insert_result insert_or_assign (K &&key, const V &value)
 Insert or replace the mapped value.
insert_result insert_or_assign (K &&key, V &&value)
 Insert or replace the mapped value.
iterator insert_or_assign (const_iterator hint, const K &key, const V &value)
 Insert or replace the mapped value, using hint when the neighbouring keys confirm it.
iterator insert_or_assign (const_iterator hint, const K &key, V &&value)
 Insert or replace the mapped value, using hint when the neighbouring keys confirm it.
iterator insert_or_assign (const_iterator hint, K &&key, const V &value)
 Insert or replace the mapped value, using hint when the neighbouring keys confirm it.
iterator insert_or_assign (const_iterator hint, K &&key, V &&value)
 Insert or replace the mapped value, using hint when the neighbouring keys confirm it.
insert_return_type insert (node_type &&handle)
 Insert an extracted node if its key is absent.
iterator insert (const_iterator hint, node_type &&handle)
 Insert an extracted node, using hint when the neighbouring keys confirm it.
node_type extract (const_iterator position)
 Unlink the entry at position and return that node.
node_type extract (const K &key)
 Unlink the entry with key and return that node.
template<class OtherCompare>
void merge (Map< K, V, OtherCompare > &source)
 Move unique keys from source into this map.
iterator erase (iterator position) noexcept
 Erase the entry at an iterator.
iterator erase (const_iterator position) noexcept
 Erase the entry at a read-only iterator.
iterator erase (const_iterator first, const_iterator last) noexcept
 Erase a half-open range.
size_type erase (const K &key) noexcept
 Erase the entry with a key.
iterator find (const K &key) noexcept
 Find an entry.
const_iterator find (const K &key) const noexcept
 Find an entry.
bool contains (const K &key) const noexcept
 Test whether a key is present.
size_type count (const K &key) const noexcept
 Return the number of entries with a key.
iterator lower_bound (const K &key) noexcept
 Return the first entry not less than a key.
const_iterator lower_bound (const K &key) const noexcept
 Return the first entry not less than a key.
iterator upper_bound (const K &key) noexcept
 Return the first entry greater than a key.
const_iterator upper_bound (const K &key) const noexcept
 Return the first entry greater than a key.
equal_range_result equal_range (const K &key) noexcept
 Return the equal range of a key.
const_equal_range_result equal_range (const K &key) const noexcept
 Return the equal range of a key.
V & operator[] (const K &key)
 Return the mapped value, inserting a value-initialized one if absent.
V & operator[] (K &&key)
 Return the mapped value, inserting a value-initialized one if absent.
V & at (const K &key)
 Return the mapped value.
const V & at (const K &key) const
 Return the mapped value.
bool operator== (const Map &other) const
 Compare entries in order.
STORMBYTE_FORCE_INLINE std::strong_ordering operator<=> (const Map &other) const
 Order maps lexicographically by key, then mapped value.
bool operator< (const Map &other) const
 Order maps lexicographically.
bool operator<= (const Map &other) const
 Order maps lexicographically.
bool operator> (const Map &other) const
 Order maps lexicographically.
bool operator>= (const Map &other) const
 Order maps lexicographically.
STORMBYTE_FORCE_INLINE operator std::map< K, V, Compare > () const
 Copy the entries into caller-owned STL storage.

Detailed Description

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
requires std::strict_weak_order<Compare, const K&, const K&>
class StormByte::Safe::Map< K, V, Compare >

Ordered unique-key map stored on Base's heap.

Template Parameters
KSafe key type.
VSafe mapped type.
CompareStrict weak ordering. A stateless comparator does not allocate. A stateful one is stored in the map object and must itself be Safe.

Nodes are allocated with Heap::Allocate. Iterators point at those nodes. Dereference returns a real Pair reference, so the map is a bidirectional range. Public results are Pair, never std::pair. node_type owns a Base node. It is not std::map::node_type. extract unlinks that node. It does not copy it. There is no allocator.

Member Typedef Documentation

◆ const_equal_range_result

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::const_equal_range_result = Pair<const_iterator, const_iterator>

Read-only lower and upper bound.

◆ const_iterator

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::const_iterator = BasicIterator<true>

Read-only iterator.

◆ const_reference

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::const_reference = const value_type&

Read-only entry reference.

◆ const_reverse_iterator

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::const_reverse_iterator = std::reverse_iterator<const_iterator>

Read-only reverse iterator.

◆ difference_type

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::difference_type = std::ptrdiff_t

Iterator distance type.

◆ equal_range_result

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::equal_range_result = Pair<iterator, iterator>

Lower and upper bound.

◆ insert_result

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::insert_result = Pair<iterator, bool>

Iterator to the entry and whether it was inserted.

◆ iterator

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::iterator = BasicIterator<false>

Mutable iterator.

◆ key_compare

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::key_compare = Compare

Key ordering.

◆ key_type

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::key_type = K

Key type.

◆ mapped_type

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::mapped_type = V

Mapped type.

◆ reference

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::reference = value_type&

Mutable entry reference.

◆ reverse_iterator

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::reverse_iterator = std::reverse_iterator<iterator>

Mutable reverse iterator.

◆ size_type

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::size_type = Size

Element count. Size, not std::size_t.

◆ value_type

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
using StormByte::Safe::Map< K, V, Compare >::value_type = Pair<const K, V>

Entry type. The key is immutable.

Constructor & Destructor Documentation

◆ Map() [1/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
StormByte::Safe::Map< K, V, Compare >::Map ( )

Construct an empty map.

Exceptions
AllocationErrorThe sentinel could not be allocated.

◆ Map() [2/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
StormByte::Safe::Map< K, V, Compare >::Map ( const Compare & compare)
explicit

Construct an empty map with a comparator.

Parameters
compareKey ordering.
Exceptions
AllocationErrorThe sentinel could not be allocated.

◆ Map() [3/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
StormByte::Safe::Map< K, V, Compare >::Map ( const Map< K, V, Compare > & other)

Copy every node into new Base blocks.

Parameters
otherSource.
Exceptions
AllocationErrorA node could not be allocated.

◆ Map() [4/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
StormByte::Safe::Map< K, V, Compare >::Map ( Map< K, V, Compare > && other)

Take the tree.

other is left empty.

Parameters
otherSource.
Exceptions
AllocationErrorThe replacement sentinel could not be allocated; the source is unchanged.

◆ Map() [5/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
STORMBYTE_FORCE_INLINE StormByte::Safe::Map< K, V, Compare >::Map ( const std::map< K, V, Compare > & other)
inlineexplicit

Copy a caller-owned STL map.

Its state is unchanged.

Parameters
otherSource.
Exceptions
AllocationErrorA node could not be allocated.

◆ Map() [6/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
STORMBYTE_FORCE_INLINE StormByte::Safe::Map< K, V, Compare >::Map ( std::map< K, V, Compare > && other)
inlineexplicit

Move elements from a caller-owned STL map and leave it empty.

Parameters
otherSource. Cleared before this function returns.
Exceptions
AllocationErrorA node could not be allocated.

◆ Map() [7/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<std::ranges::input_range R>
requires std::convertible_to<std::ranges::range_reference_t<R>, value_type>
STORMBYTE_FORCE_INLINE StormByte::Safe::Map< K, V, Compare >::Map ( std::from_range_t ,
R && range )
inlineexplicit

Copy the entries of range.

Template Parameters
RInput range of value_type.
Parameters
rangeSource. Instantiated in the caller.
Exceptions
AllocationErrorA node could not be allocated.

◆ Map() [8/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
StormByte::Safe::Map< K, V, Compare >::Map ( std::initializer_list< value_type > values)

Insert every entry of an initializer list.

Parameters
valuesEntries.
Exceptions
AllocationErrorA node could not be allocated.

◆ ~Map()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
StormByte::Safe::Map< K, V, Compare >::~Map ( )
noexcept

Destroy every node through Base.

Member Function Documentation

◆ at() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
V & StormByte::Safe::Map< K, V, Compare >::at ( const K & key)

Return the mapped value.

Parameters
keyLookup key.
Returns
Mapped value. Valid until the entry is erased.
Exceptions
OutOfBoundsErrorThe key is absent. There is no numeric bound, so the error carries no index.

◆ at() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const V & StormByte::Safe::Map< K, V, Compare >::at ( const K & key) const

Return the mapped value.

Parameters
keyLookup key.
Returns
Mapped value. Valid until the entry is erased.
Exceptions
OutOfBoundsErrorThe key is absent. There is no numeric bound, so the error carries no index.

◆ begin() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_iterator StormByte::Safe::Map< K, V, Compare >::begin ( ) const
noexcept

Return a read-only iterator to the first entry.

Returns
Read-only iterator.

◆ begin() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::begin ( )
noexcept

Return a mutable iterator to the first entry.

Returns
Mutable iterator.

◆ cbegin()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_iterator StormByte::Safe::Map< K, V, Compare >::cbegin ( ) const
noexcept

Return a read-only iterator to the first entry.

Returns
Read-only iterator.

◆ cend()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_iterator StormByte::Safe::Map< K, V, Compare >::cend ( ) const
noexcept

Return the read-only end iterator.

Returns
End iterator.

◆ clear()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
void StormByte::Safe::Map< K, V, Compare >::clear ( )
noexcept

Destroy every node.

◆ contains()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
bool StormByte::Safe::Map< K, V, Compare >::contains ( const K & key) const
noexcept

Test whether a key is present.

Parameters
keyLookup key.
Returns
Whether the key is present.

◆ count()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
size_type StormByte::Safe::Map< K, V, Compare >::count ( const K & key) const
noexcept

Return the number of entries with a key.

Parameters
keyLookup key.
Returns
Zero or one.

◆ crbegin()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_reverse_iterator StormByte::Safe::Map< K, V, Compare >::crbegin ( ) const
inlinenoexcept

Return a read-only reverse iterator to the last entry.

Returns
Reverse iterator.

◆ crend()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_reverse_iterator StormByte::Safe::Map< K, V, Compare >::crend ( ) const
inlinenoexcept

Return the read-only reverse end iterator.

Returns
Reverse end iterator.

◆ emplace()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class... Args>
insert_result StormByte::Safe::Map< K, V, Compare >::emplace ( Args &&... args)

Construct an entry from arguments forwarded to value_type.

Template Parameters
ArgsEntry constructor argument types.
Parameters
argsArguments forwarded to value_type.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ emplace_hint()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class... Args>
iterator StormByte::Safe::Map< K, V, Compare >::emplace_hint ( const_iterator hint,
Args &&... args )

Construct an entry from arguments, using hint when the neighbouring keys confirm it.

Template Parameters
ArgsEntry constructor argument types.
Parameters
hintSuggested position.
argsArguments forwarded to value_type.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ empty()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
bool StormByte::Safe::Map< K, V, Compare >::empty ( ) const
inlinenoexcept

Test whether the map has no entries.

Returns
Whether the map is empty.

◆ end() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_iterator StormByte::Safe::Map< K, V, Compare >::end ( ) const
noexcept

Return the read-only end iterator.

Returns
End iterator.

◆ end() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::end ( )
noexcept

Return the mutable end iterator.

Returns
End iterator.

◆ equal_range() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_equal_range_result StormByte::Safe::Map< K, V, Compare >::equal_range ( const K & key) const
noexcept

Return the equal range of a key.

Parameters
keyLookup key.
Returns
Lower and upper bound. They are equal when the key is absent.

◆ equal_range() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
equal_range_result StormByte::Safe::Map< K, V, Compare >::equal_range ( const K & key)
noexcept

Return the equal range of a key.

Parameters
keyLookup key.
Returns
Lower and upper bound. They are equal when the key is absent.

◆ erase() [1/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
size_type StormByte::Safe::Map< K, V, Compare >::erase ( const K & key)
noexcept

Erase the entry with a key.

Parameters
keyLookup key.
Returns
Number of erased entries, zero or one.

◆ erase() [2/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::erase ( const_iterator first,
const_iterator last )
noexcept

Erase a half-open range.

Parameters
firstFirst entry to erase.
lastPast-the-end entry.
Returns
Iterator following the erased range.

◆ erase() [3/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::erase ( const_iterator position)
noexcept

Erase the entry at a read-only iterator.

Parameters
positionEntry to erase.
Returns
Iterator following the erased entry.

◆ erase() [4/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::erase ( iterator position)
noexcept

Erase the entry at an iterator.

Parameters
positionEntry to erase.
Returns
Iterator following the erased entry.

◆ extract() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
node_type StormByte::Safe::Map< K, V, Compare >::extract ( const K & key)

Unlink the entry with key and return that node.

Parameters
keyLookup key.
Returns
Owning handle. Empty when the key is absent.

◆ extract() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
node_type StormByte::Safe::Map< K, V, Compare >::extract ( const_iterator position)

Unlink the entry at position and return that node.

Parameters
positionEntry to extract.
Returns
Owning handle. Empty when position is end.

◆ find() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_iterator StormByte::Safe::Map< K, V, Compare >::find ( const K & key) const
noexcept

Find an entry.

Parameters
keyLookup key.
Returns
Iterator to the entry, or end.

◆ find() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::find ( const K & key)
noexcept

Find an entry.

Parameters
keyLookup key.
Returns
Iterator to the entry, or end.

◆ insert() [1/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
insert_result StormByte::Safe::Map< K, V, Compare >::insert ( const value_type & entry)

Insert a copy of an entry.

Parameters
entryEntry to insert.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert() [2/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::insert ( const_iterator hint,
const value_type & entry )

Insert a copy of an entry, using hint when the neighbouring keys confirm it.

Parameters
hintSuggested position.
entryEntry to insert.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert() [3/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::insert ( const_iterator hint,
node_type && handle )

Insert an extracted node, using hint when the neighbouring keys confirm it.

Parameters
hintSuggested position.
handleNode. Emptied when inserted.
Returns
Iterator to the entry, or end when handle was empty.

◆ insert() [4/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::insert ( const_iterator hint,
value_type && entry )

Insert a moved entry, using hint when the neighbouring keys confirm it.

Parameters
hintSuggested position.
entryEntry to insert.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert() [5/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class InputIt>
STORMBYTE_FORCE_INLINE void StormByte::Safe::Map< K, V, Compare >::insert ( InputIt first,
InputIt last )
inline

Insert every entry in [first, last).

Template Parameters
InputItInput iterator of entries.
Parameters
firstStart.
lastEnd.
Exceptions
AllocationErrorA node could not be allocated.

◆ insert() [6/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
insert_return_type StormByte::Safe::Map< K, V, Compare >::insert ( node_type && handle)

Insert an extracted node if its key is absent.

The same node is linked.

Parameters
handleNode. Emptied when inserted.
Returns
Position, whether it was inserted, and the rejected node.

◆ insert() [7/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class P>
requires Type::ConstructibleFrom<typename Map<K, V, Compare>::value_type, P> && (!Type::SameAs<std::remove_cvref_t<P>, typename Map<K, V, Compare>::value_type>)
insert_result StormByte::Safe::Map< K, V, Compare >::insert ( P && entry)

Insert an entry constructed from a compatible value.

Template Parameters
PSource type. value_type must be constructible from it.
Parameters
entrySource entry.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert() [8/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
void StormByte::Safe::Map< K, V, Compare >::insert ( std::initializer_list< value_type > values)

Insert every entry of an initializer list.

Parameters
valuesEntries.
Exceptions
AllocationErrorA node could not be allocated.

◆ insert() [9/9]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
insert_result StormByte::Safe::Map< K, V, Compare >::insert ( value_type && entry)

Insert a moved entry.

Parameters
entryEntry to insert.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [1/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
insert_result StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( const K & key,
const V & value )

Insert or replace the mapped value.

Parameters
keyLookup key.
valueReplacement value.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [2/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
insert_result StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( const K & key,
V && value )

Insert or replace the mapped value.

Parameters
keyLookup key.
valueReplacement value, moved when assigned.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [3/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( const_iterator hint,
const K & key,
const V & value )

Insert or replace the mapped value, using hint when the neighbouring keys confirm it.

Parameters
hintSuggested position.
keyLookup key.
valueReplacement value.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [4/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( const_iterator hint,
const K & key,
V && value )

Insert or replace the mapped value, using hint when the neighbouring keys confirm it.

Parameters
hintSuggested position.
keyLookup key.
valueReplacement value, moved when assigned.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [5/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( const_iterator hint,
K && key,
const V & value )

Insert or replace the mapped value, using hint when the neighbouring keys confirm it.

Parameters
hintSuggested position.
keyLookup key, moved when inserted.
valueReplacement value.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [6/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( const_iterator hint,
K && key,
V && value )

Insert or replace the mapped value, using hint when the neighbouring keys confirm it.

Parameters
hintSuggested position.
keyLookup key, moved when inserted.
valueReplacement value, moved when assigned.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [7/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
insert_result StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( K && key,
const V & value )

Insert or replace the mapped value.

Parameters
keyLookup key, moved when inserted.
valueReplacement value.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_or_assign() [8/8]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
insert_result StormByte::Safe::Map< K, V, Compare >::insert_or_assign ( K && key,
V && value )

Insert or replace the mapped value.

Parameters
keyLookup key, moved when inserted.
valueReplacement value, moved when assigned.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ insert_range()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<std::ranges::input_range R>
requires std::convertible_to<std::ranges::range_reference_t<R>, value_type>
STORMBYTE_FORCE_INLINE void StormByte::Safe::Map< K, V, Compare >::insert_range ( R && range)
inline

Insert a copy of range.

Template Parameters
RInput range of entries.
Parameters
rangeSource. Instantiated in the caller.
Exceptions
AllocationErrorA node could not be allocated.

◆ key_comp()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
key_compare StormByte::Safe::Map< K, V, Compare >::key_comp ( ) const
inline

Return the key ordering.

Returns
Comparator.

◆ lower_bound() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_iterator StormByte::Safe::Map< K, V, Compare >::lower_bound ( const K & key) const
noexcept

Return the first entry not less than a key.

Parameters
keyLookup key.
Returns
Iterator to the lower bound, or end.

◆ lower_bound() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::lower_bound ( const K & key)
noexcept

Return the first entry not less than a key.

Parameters
keyLookup key.
Returns
Iterator to the lower bound, or end.

◆ max_size()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
size_type StormByte::Safe::Map< K, V, Compare >::max_size ( ) const
inlinenoexcept

Return the largest representable entry count.

Returns
Maximum size.

◆ merge()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class OtherCompare>
void StormByte::Safe::Map< K, V, Compare >::merge ( Map< K, V, OtherCompare > & source)

Move unique keys from source into this map.

The node is transferred, not copied.

Template Parameters
OtherCompareSource ordering.
Parameters
sourceMap to drain. Entries whose key is already present stay in source.

◆ operator std::map< K, V, Compare >()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
STORMBYTE_FORCE_INLINE StormByte::Safe::Map< K, V, Compare >::operator std::map< K, V, Compare > ( ) const
inlineexplicit

Copy the entries into caller-owned STL storage.

Returns
A std::map owned by the caller.

◆ operator<()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
bool StormByte::Safe::Map< K, V, Compare >::operator< ( const Map< K, V, Compare > & other) const

Order maps lexicographically.

Parameters
otherMap to compare.
Returns
Whether this map precedes other.

◆ operator<=()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
bool StormByte::Safe::Map< K, V, Compare >::operator<= ( const Map< K, V, Compare > & other) const

Order maps lexicographically.

Parameters
otherMap to compare.
Returns
Whether this map precedes or equals other.

◆ operator<=>()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
STORMBYTE_FORCE_INLINE std::strong_ordering StormByte::Safe::Map< K, V, Compare >::operator<=> ( const Map< K, V, Compare > & other) const

Order maps lexicographically by key, then mapped value.

Parameters
otherMap to compare.
Returns
Ordering.

◆ operator=() [1/5]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
Map & StormByte::Safe::Map< K, V, Compare >::operator= ( const Map< K, V, Compare > & other)

Copy-assign.

The previous tree is released only after the copy exists.

Parameters
otherSource.
Returns
This map.
Exceptions
AllocationErrorA node could not be allocated.

◆ operator=() [2/5]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
STORMBYTE_FORCE_INLINE Map & StormByte::Safe::Map< K, V, Compare >::operator= ( const std::map< K, V, Compare > & other)
inline

Copy-assign a caller-owned STL map.

Its state is unchanged.

Parameters
otherSource.
Returns
This map.
Exceptions
AllocationErrorA node could not be allocated.

◆ operator=() [3/5]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
Map & StormByte::Safe::Map< K, V, Compare >::operator= ( Map< K, V, Compare > && other)
noexcept

Move-assign.

other is left empty.

Parameters
otherSource.
Returns
This map.

◆ operator=() [4/5]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
Map & StormByte::Safe::Map< K, V, Compare >::operator= ( std::initializer_list< value_type > values)

Replace the contents with an initializer list.

Parameters
valuesEntries.
Returns
This map.
Exceptions
AllocationErrorA node could not be allocated.

◆ operator=() [5/5]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
STORMBYTE_FORCE_INLINE Map & StormByte::Safe::Map< K, V, Compare >::operator= ( std::map< K, V, Compare > && other)
inline

Move-assign elements from a caller-owned STL map and leave it empty.

Parameters
otherSource. Cleared before this function returns.
Returns
This map.
Exceptions
AllocationErrorA node could not be allocated.

◆ operator==()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
bool StormByte::Safe::Map< K, V, Compare >::operator== ( const Map< K, V, Compare > & other) const

Compare entries in order.

Parameters
otherMap to compare.
Returns
Whether both maps contain the same entries.

◆ operator>()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
bool StormByte::Safe::Map< K, V, Compare >::operator> ( const Map< K, V, Compare > & other) const

Order maps lexicographically.

Parameters
otherMap to compare.
Returns
Whether this map follows other.

◆ operator>=()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
bool StormByte::Safe::Map< K, V, Compare >::operator>= ( const Map< K, V, Compare > & other) const

Order maps lexicographically.

Parameters
otherMap to compare.
Returns
Whether this map follows or equals other.

◆ operator[]() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
V & StormByte::Safe::Map< K, V, Compare >::operator[] ( const K & key)

Return the mapped value, inserting a value-initialized one if absent.

Parameters
keyLookup key.
Returns
Mapped value. Valid until the entry is erased.
Exceptions
AllocationErrorThe node could not be allocated.

◆ operator[]() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
V & StormByte::Safe::Map< K, V, Compare >::operator[] ( K && key)

Return the mapped value, inserting a value-initialized one if absent.

Parameters
keyLookup key, moved when inserted.
Returns
Mapped value. Valid until the entry is erased.
Exceptions
AllocationErrorThe node could not be allocated.

◆ rbegin() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_reverse_iterator StormByte::Safe::Map< K, V, Compare >::rbegin ( ) const
inlinenoexcept

Return a read-only reverse iterator to the last entry.

Returns
Reverse iterator.

◆ rbegin() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
reverse_iterator StormByte::Safe::Map< K, V, Compare >::rbegin ( )
inlinenoexcept

Return a reverse iterator to the last entry.

Returns
Reverse iterator.

◆ rend() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_reverse_iterator StormByte::Safe::Map< K, V, Compare >::rend ( ) const
inlinenoexcept

Return the read-only reverse end iterator.

Returns
Reverse end iterator.

◆ rend() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
reverse_iterator StormByte::Safe::Map< K, V, Compare >::rend ( )
inlinenoexcept

Return the reverse end iterator.

Returns
Reverse end iterator.

◆ size()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
size_type StormByte::Safe::Map< K, V, Compare >::size ( ) const
inlinenoexcept

Return the entry count.

Returns
Entry count.

◆ swap()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
void StormByte::Safe::Map< K, V, Compare >::swap ( Map< K, V, Compare > & other)
noexcept

Exchange trees.

Does not allocate.

Parameters
otherMap to exchange with.

◆ try_emplace() [1/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class... Args>
insert_result StormByte::Safe::Map< K, V, Compare >::try_emplace ( const K & key,
Args &&... args )

Construct an entry in a new node if the key is absent.

Template Parameters
ArgsMapped constructor argument types.
Parameters
keyLookup key.
argsArguments forwarded to V. None value-initializes V.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ try_emplace() [2/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class... Args>
iterator StormByte::Safe::Map< K, V, Compare >::try_emplace ( const_iterator hint,
const K & key,
Args &&... args )

Construct an entry if the key is absent, using hint when the neighbouring keys confirm it.

Template Parameters
ArgsMapped constructor argument types.
Parameters
hintSuggested position.
keyLookup key.
argsArguments forwarded to V.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ try_emplace() [3/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class... Args>
iterator StormByte::Safe::Map< K, V, Compare >::try_emplace ( const_iterator hint,
K && key,
Args &&... args )

Construct an entry if the key is absent, using hint when the neighbouring keys confirm it.

Template Parameters
ArgsMapped constructor argument types.
Parameters
hintSuggested position.
keyLookup key, moved when inserted.
argsArguments forwarded to V.
Returns
Iterator to the entry.
Exceptions
AllocationErrorThe node could not be allocated.

◆ try_emplace() [4/4]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
template<class... Args>
insert_result StormByte::Safe::Map< K, V, Compare >::try_emplace ( K && key,
Args &&... args )

Construct an entry in a new node if the key is absent.

Template Parameters
ArgsMapped constructor argument types.
Parameters
keyLookup key, moved when inserted.
argsArguments forwarded to V.
Returns
Iterator to the entry and whether it was inserted.
Exceptions
AllocationErrorThe node could not be allocated.

◆ upper_bound() [1/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
const_iterator StormByte::Safe::Map< K, V, Compare >::upper_bound ( const K & key) const
noexcept

Return the first entry greater than a key.

Parameters
keyLookup key.
Returns
Iterator to the upper bound, or end.

◆ upper_bound() [2/2]

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
iterator StormByte::Safe::Map< K, V, Compare >::upper_bound ( const K & key)
noexcept

Return the first entry greater than a key.

Parameters
keyLookup key.
Returns
Iterator to the upper bound, or end.

◆ value_comp()

template<Type::SafeValue K, Type::SafeValue V, class Compare = std::less<K>>
value_compare StormByte::Safe::Map< K, V, Compare >::value_comp ( ) const
inline

Return an entry comparator that uses the key ordering.

Returns
Entry comparator.

The documentation for this class was generated from the following file:
  • lib/public/StormByte/safe/map.hxx