bsl::unordered

This class template implements a value‐semantic container type holding an unordered set of KEY‐VALUE pairs having unique keys that provide a mapping from keys (of template parameter type KEY) to their associated mapped values (of template parameter type VALUE).

Synopsis

Declared in <bslstl_unorderedmap.h>

template<
    class KEY,
    class VALUE,
    class HASH = bsl::hash<KEY>,
    class EQUAL = bsl::equal_to<KEY>,
    class ALLOCATOR = bsl::allocator<bsl::pair<KEY const, VALUE>>>
class unordered_map;

Description

This class: * supports a complete set of value‐semantic operations * is exception‐neutral (agnostic except for the at method) * is alias‐safe * is const thread‐safe For terminology see {`bsldoc_glossary`}.

Type Aliases

Name

Description

allocator_type

This typedef is an alias to the (template parameter) ALLOCATOR.

const_iterator

This typedef is an alias to HashTableIterator<const value_type>.

const_local_iterator

This typedef is an alias to HashTableBucketIterator<const value_type>.

const_pointer

This typedef is an alias to AllocatorTraits::const_pointer.

const_reference

This typedef is an alias to const value_type&.

difference_type

This typedef is an alias to AllocatorTraits::difference_type.

hasher

This typedef is an alias to the (template parameter) HASH.

iterator

This typedef is an alias to HashTableIterator<value_type>.

key_equal

This typedef is an alias to the (template parameter) EQUAL.

key_type

This typedef is an alias to the (template parameter) KEY.

local_iterator

This typedef is an alias to HashTableBucketIterator<value_type>.

mapped_type

This typedef is an alias to the (template parameter) VALUE.

pointer

This typedef is an alias to AllocatorTraits::pointer.

reference

This typedef is an alias to value_type&.

size_type

This typedef is an alias to AllocatorTraits::size_type.

value_type

This typedef is an alias to bsl::pair<const KEY, VALUE>.

Member Functions

Name

Description

unordered_map [constructor]

Constructors

~unordered_map [destructor]

Destroy this object and each of its elements.

Assignment operators

at overloads

begin overloads

bucket overloads

Return the number of buckets in the array of buckets maintained by this unordered map.

bucket_size

Return the number of elements contained in the bucket at the specified index in the array of buckets maintained by this unordered map. The behavior is undefined unless index < bucket_count().

cbegin

cbegin overloads

cend

cend overloads

clear

Remove all entries from this unordered map. Note that this unordered map will be empty after calling this method, but allocated memory may be retained for future use.

contains

Return true if this unordered map contains an element whose key is equivalent to the specified key.

count

count overloads

emplace

Insert into this unordered map a newly‐created value_type object, constructed by forwarding get_allocator() (if required) and the specified (variable number of) args to the corresponding constructor of value_type, if a key equivalent to such a value does not already exist in this map; otherwise, this method has no effect (other than possibly creating a temporary value_type object). Return a pair whose first member is an iterator referring to the (possibly newly created and inserted) object in this map whose key is equivalent to that of an object constructed from args, and whose second member is true if a new value was inserted, and false if an equivalent key was already present. This method requires that the (template parameter) types KEY and VALUE both be emplace‐constructible from args (see {Requirements on value_type}).

emplace_hint

Insert into this unordered map a newly‐created value_type object, constructed by forwarding get_allocator() (if required) and the specified (variable number of) args to the corresponding constructor of value_type, if a key equivalent to such a value does not already exist in this map; otherwise, this method has no effect (other than possibly creating a temporary value_type object). Return an iterator referring to the (possibly newly created and inserted) object in this map whose key is equivalent to that of an object constructed from args. The average and worst case complexity of this operation is not affected by the specified hint. This method requires that the (template parameter) types KEY and VALUE both be emplace‐constructible from args (see {Requirements on value_type}). The behavior is undefined unless hint is an iterator in the range [begin() .. end()] (both endpoints included). Note that hint is ignored (other than possibly asserting its validity in some build modes).

empty

Return true if this unordered map contains no elements, and false otherwise.

end

end overloads

equal_range

equal_range overloads

erase

erase overloads

find

find overloads

get_allocator

Return (a copy of) the allocator used for memory allocation by this unordered map.

hash_function

Return (a copy of) the unary hash functor used by this unordered map to generate a hash value (of type size_type) for a key_type object.

insert

insert overloads

insert_or_assign

insert_or_assign overloads

insert_range

Insert into this map the value of each value_type object in the specified range if a key equivalent to the object is not already contained in this set. The (template parameter) type RANGE must meet the requirements the C++20 standard [ranges]providing access to values of a type convertible to value_type, and value_type must be emplace‐constructible from *i into this set, where i is a dereferenceable iterator obtained from range (see {Requirements on KEY}). The behavior is undefined if range overlaps this map.

key_eq

Return (a copy of) binary the key‐equality functor used by this unordered map that returns true if two key_type objects are equivalent, and false otherwise.

load_factor

Return the current ratio between the size of this unordered map and the number of buckets. The load factor is a measure of how full the container is, and a higher load factor typically leads to an increased number of collisions, thus resulting in a loss of performance.

max_bucket_count

Return a theoretical upper bound on the largest number of buckets that this unordered map could possibly manage. Note that there is no guarantee that the unordered map can successfully grow to the returned size, or even close to that size, without running out of resources.

max_load_factor

max_load_factor overloads

max_size

Return a theoretical upper bound on the largest number of elements that this unordered map could possibly hold. Note that there is no guarantee that the unordered map can successfully grow to the returned size, or even close to that size, without running out of resources.

operator[]

Subscript operators

rehash

Change the size of the array of buckets maintained by this unordered map to at least the specified numBuckets, and redistribute all the contained elements into the new sequence of buckets, according to their hash values. After this call, load_factor will be less than or equal to max_load_factor. This operation has no effect if rehashing the elements into numBuckets would cause this map to exceed its max_load_factor.

reserve

Increase the number of buckets of this set to a quantity such that the ratio between the specified numElements and this quantity does not exceed max_load_factor. Note that this guarantees that, after the reserve, elements can be inserted to grow the container to size() == numElements without rehashing. Also note that memory allocations may still occur when growing the container to `size() == numElements`. Also note that this operation has no effect if numElements <= size().

size

Return the number of elements in this unordered map.

swap

Exchange the value, hasher, key‐equality functor, and max_load_factor of this object with those of the specified other object; also exchange the allocator of this object with that of other if the (template parameter) type ALLOCATOR has the propagate_on_container_swap trait, and do not modify either allocator otherwise. This method provides the no‐throw exception‐safety guarantee if and only if both the (template parameter) types HASH and EQUAL provide no‐throw swap operations; if an exception is thrown, both objects are left in valid but unspecified states. This operation guarantees O[1] complexity. The behavior is undefined unless either this object was created with the same allocator as other or ALLOCATOR has the propagate_on_container_swap trait.

try_emplace

try_emplace overloads

Specializations

Name

Description

unordered_map<basic_string<char>, Json, TransparentHash, TransparentEqualTo>

Deduction Guides

Name

Description

unordered_map<KEY, VALUE>

Deduce the template parameters KEY and VALUE from the value_type of the initializer_list supplied to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<bsl::pair<const KEY, VALUE>>.

unordered_map<KEY, VALUE>

Deduce the template parameters KEY and VALUE from the value_type of the iterators supplied to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<bsl::pair<const KEY, VALUE>>.

unordered_map<KEY, VALUE>

unordered_map<KEY, VALUE, HASH>

Deduce the template parameters KEY and VALUE from the value_type of the initializer_list supplied to the constructor of unordered_map. Deduce the template parameter HASH from the other parameters supplied to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<bsl::pair<const KEY, VALUE>>.

unordered_map<KEY, VALUE, HASH>

Deduce the template parameters KEY and VALUE from the value_type of the iterators supplied to the constructor of unordered_map. Deduce the template parameter HASH from the other parameters passed to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<bsl::pair<const KEY, VALUE>>.

unordered_map<KEY, VALUE, HASH, EQUAL>

Deduce the template parameters KEY and VALUE from the value_type of the initializer_list supplied to the constructor of unordered_map. Deduce the template parameters HASH and EQUAL from the other parameters supplied to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<bsl::pair<const KEY, VALUE>>.

unordered_map<KEY, VALUE, HASH, EQUAL>

Deduce the template parameters KEY and VALUE from the value_type of the iterators supplied to the constructor of unordered_map. Deduce the template parameters HASH and "EQUAL' from the other parameters passed to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator is convertible to bsl::allocator<bsl::pair<const KEY, VALUE>>.

unordered_map<KEY, VALUE, HASH, EQUAL, ALLOCATOR>

Deduce the template parameters KEY and VALUE from the value_type of the initializer_list supplied to the constructor of unordered_map. Deduce the template parameters HASH, EQUAL and ALLOCATOR from the other parameters supplied to the constructor of unordered_map. This deduction guide does not participate unless: (1) the supplied HASH is invokable with a KEY, (2) the supplied EQUAL is invokable with two `KEY`s, and (3) the supplied allocator meets the requirements of a standard allocator.

unordered_map<KEY, VALUE, HASH, EQUAL, ALLOCATOR>

Deduce the template parameters KEY and VALUE from the value_type of the iterators supplied to the constructor of unordered_map. Deduce the template parameters HASH, EQUAL and ALLOCATOR from the other parameters passed to the constructor of unordered_map. This deduction guide does not participate unless: (1) the supplied HASH is invokable with a KEY, (2) the supplied EQUAL is invokable with two `KEY`s, and (3) the supplied allocator meets the requirements of a standard allocator.

unordered_map<KEY, VALUE, HASH, bsl::equal_to<KEY>, ALLOCATOR>

Deduce the template parameters KEY and VALUE from the value_type of the initializer_list supplied to the constructor of unordered_map. Deduce the template parameters HASH and ALLOCATOR from the other parameters supplied to the constructor of unordered_map. This deduction guide does not participate unless the supplied HASH is invokable with a KEY, and the supplied allocator meets the requirements of a standard allocator.

unordered_map<KEY, VALUE, HASH, bsl::equal_to<KEY>, ALLOCATOR>

Deduce the template parameters KEY and VALUE from the value_type of the iterators supplied to the constructor of unordered_map. Deduce the template parameters HASH and ALLOCATOR from the other parameters passed to the constructor of unordered_map. This deduction guide does not participate unless the supplied hash is invokable with a KEY and the supplied allocator meets the requirements of a standard allocator.

unordered_map<KEY, VALUE, bsl::hash<KEY>, bsl::equal_to<KEY>, ALLOCATOR>

Deduce the template parameters KEY and VALUE from the value_type of the initializer_list supplied to the constructor of unordered_map. Deduce the template parameter ALLOCATOR from the other parameters supplied to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.

unordered_map<KEY, VALUE, bsl::hash<KEY>, bsl::equal_to<KEY>, ALLOCATOR>

Deduce the template parameters KEY and VALUE from the value_type of the iterators supplied to the constructor of unordered_map. Deduce the template parameter ALLOCATOR from the other parameter passed to the constructor of unordered_map. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.

unordered_map<KEY, VALUE, bsl::hash<KEY>, bsl::equal_to<KEY>, ALLOCATOR>

Friends

Name

Description

bsl::operator==

Return true if the specified lhs and rhs objects have the same value, and false otherwise.

Non-Member Functions

Name

Description

erase_if

Erase all the elements in the specified unordered_map m that satisfy the specified predicate predicate. Return the number of elements erased.

operator==

Return true if the specified lhs and rhs objects have the same value, and false otherwise. Two unordered_map objects have the same value if they have the same number of key‐value pairs, and for each key‐value pair that is contained in lhs there is a key‐value pair contained in rhs having the same value, and vice versa. Note that this method requires that the (template parameter) types KEY and VALUE both be equality‐comparable (see {Requirements on value_type}).

swap

Exchange the value, hasher, key‐equality functor, and max_load_factor of the specified a object with those of the specified b object; also exchange the allocator of a with that of b if the (template parameter) type ALLOCATOR has the propagate_on_container_swap trait, and do not modify either allocator otherwise. This function provides the no‐throw exception‐safety guarantee if and only if both the (template parameter) types HASH and EQUAL provide no‐throw swap operations; if an exception is thrown, both objects are left in valid but unspecified states. This operation guarantees O[1] complexity. The behavior is undefined unless either a was created with the same allocator as b or ALLOCATOR has the propagate_on_container_swap trait.

Created with MrDocs

bsl::unordered_map

Synopsis

Description

Type Aliases

Member Functions

Specializations

Deduction Guides

Friends

Non-Member Functions