template<classKey,classT,classCompare=std::less<Key>,classKeyContainer=std::vector<Key>,classMappedContainer=std::vector<T>>classflat_map;(since C++23)The flat map is a
that gives the functionality of an associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function Compare.
The class template flat_map acts as a wrapper to the two underlying containers, passed as objects of type KeyContainer and MappedContainer respectively. The first container is sorted, and for each key its corresponding value is in the second container at the same index (offset). The number of elements in both containers is the same.
Everywhere the standard library uses the
requirements, uniqueness is determined by using the equivalence relation. Informally, two objects a and b are considered equivalent if neither compares less than the other: !comp(a,b)&&!comp(b,a).
std::flat_map meets the requirements of
,
,
optional container requirements
, and all requirements of
(including logarithmic search complexity), except that:
requirements related to nodes are not applicable,
iterator invalidation requirements differ,
the complexity of insertion and erasure operations is linear.
A flat map supports most
's operations that use unique keys.
All member functions of std::flat_map are constexpr: it is possible to create and use std::flat_map objects in the evaluation of a constant expression.
However, defining a constexprstd::flat_map variable is generally an error, because constant evaluation requires any dynamically allocated storage to be released in the same evaluation, which is usually not the case with std::flat_map's initializer.
(since C++26)Iterator invalidation
Template parameters
Key - The type of the keys. The program is ill-formed if Key is not the same type as KeyContainer::value_type. T - The type of mapped values. The program is ill-formed if T is not the same type as MappedContainer::value_type. Compare - A
type providing a strict weak ordering. KeyContainer
MappedContainer - The types of the underlying
to store keys and mapped values correspondingly. The iterators of such containers should satisfy
or model
. Invocations of their member functions size and max_size should not exit via an exception. The standard containers
and
satisfy these requirements.
Member types
Type Definition key_container_typeKeyContainer
mapped_container_typeMappedContainer
key_typeKey
mapped_typeT
value_typestd::pair<key_type,mapped_type>
key_compareCompare
referencestd::pair<constkey_type&,mapped_type&>
const_referencestd::pair<constkey_type&,constmapped_type&>
size_type
difference_type
iteratorimplementation-defined
,
(since C++26) and
to value_type
const_iteratorimplementation-defined
,
(since C++26) and
to constvalue_type
reverse_iteratorstd::reverse_iterator<iterator>
const_reverse_iteratorstd::reverse_iterator<const_iterator>
containerstype describing the underlying containers structcontainers{key_container_typekeys;mapped_container_typevalues;};
Member classes
Member objects
Member Description containersc(private)the adapted containers
(exposition-only member object*)key_comparecompare(private)the comparison function object
(exposition-only member object*)Member functions
constructs the flat_map
(public member function)
(destructor)
(implicitly declared)
destroys every element of the container adaptor
(public member function)
assigns values to the container adaptor
(public member function)
Element access
access specified element with bounds checking
(public member function)
access or insert specified element
(public member function)
Iterators
returns an iterator to the beginning
(public member function)
returns an iterator to the end
(public member function)
returns a reverse iterator to the beginning
(public member function)
returns a reverse iterator to the end
(public member function)
Capacity
checks whether the container adaptor is empty
(public member function)
returns the number of elements
(public member function)
returns the maximum possible number of elements
(public member function)
Modifiers
constructs element in-place
(public member function)
constructs elements in-place using a hint
(public member function)
inserts in-place if the key does not exist, does nothing if the key exists
(public member function)
inserts elements
(public member function)
inserts a range of elements
(public member function)
inserts an element or assigns to the current element if the key already exists
(public member function)
extracts the underlying containers
(public member function)
replaces the underlying containers
(public member function)
erases elements
(public member function)
swaps the contents
(public member function)
clears the contents
(public member function)
Lookup
finds element with specific key
(public member function)
returns the number of elements matching specific key
(public member function)
checks if the container contains element with specific key
(public member function)
returns an iterator to the first element not less than the given key
(public member function)
returns an iterator to the first element greater than the given key
(public member function)
returns range of elements matching a specific key
(public member function)
Observers
returns the function that compares keys
(public member function)
returns the function that compares keys in objects of type value_type
(public member function)
direct access to the underlying keys container
(public member function)
direct access to the underlying values container
(public member function)
Non-member functions
Helper classes
Tags
Notes
The member types iterator and const_iterator may be aliases to the same type. This means defining a pair of function overloads using the two types as parameter types may violate the
. Since iterator is convertible to const_iterator, a single function with a const_iterator as parameter type will work instead.
macro ValueStdFeature
(C++23)std::flat_map and std::flat_multimap
(C++26)Constexpr std::flat_mapExample
See also
(C++23)
adapts two containers to provide a collection of key-value pairs, sorted by keys
(class template)
collection of key-value pairs, sorted by keys, keys are unique
(class template)
(C++11)
collection of key-value pairs, hashed by keys, keys are unique
(class template)