View source for cpp/container/flat map

{{cpp/title|flat_map}}
{{cpp/container/flat_map/navbar}}
{{ddcl|header=flat_map|since=c++23|1=
template<
    class Key,
    class T,
    class Compare = std::less<Key>,
    class KeyContainer = std::vector<Key>,
    class MappedContainer = std::vector<T>
> class flat_map;
}}

The flat map is a [[cpp/container#Container adaptors|container adaptor]] that gives the functionality of an associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function {{tt|Compare}}.

The class template {{tt|flat_map}} acts as a wrapper to the two underlying containers, passed as objects of type {{tt|KeyContainer}} and {{tt|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 {{named req|Compare}} requirements, uniqueness is determined by using the equivalence relation. Informally, two objects {{c|a}} and {{c|b}} are considered equivalent if neither compares less than the other: {{c|!comp(a, b) && !comp(b, a)}}.

{{tt|std::flat_map}} meets the requirements of {{named req|Container}}, {{named req|ReversibleContainer}}, {{lsd|cpp/named_req/Container#Optional container requirements}}, and all requirements of {{named req|AssociativeContainer}} (including logarithmic search complexity), except that:
* requirements related to nodes are not applicable,
* iterator invalidation requirements differ, <!--TODO: describe iterator/pointer invalidation properties, maybe per each function, in their pages -->
* the complexity of insertion and erasure operations is linear.

A flat map supports most {{named req|AssociativeContainer}}'s operations that use unique keys.

===Iterator invalidation===
{{todo}} <!-- TODO: see e.g. [[cpp/container/unordered_map#Iterator invalidation]] as a basis -->

===Template parameters===
{{par begin}}
{{par|Key|The type of the keys. The program is ill-formed if {{tt|Key}} is not the same type as {{tt|KeyContainer::value_type}}.}}
{{par|T|The type of mapped values. The program is ill-formed if {{tt|T}} is not the same type as {{tt|MappedContainer::value_type}}.}}
{{par|Compare|A {{named req|Compare}} type providing a strict weak ordering.}}
{{par|KeyContainer<br>MappedContainer|The types of the underlying {{named req|SequenceContainer}} to store keys and mapped values correspondingly. The iterators of such containers should satisfy {{named req|RandomAccessIterator}} or model {{lconcept|random_access_iterator}}. Invocations of their member functions {{tt|size}} and {{tt|max_size}} should not exit via an exception.

The standard containers {{lc|std::vector}} and {{lc|std::deque}} satisfy these requirements.}}{{par end}}
<!---->
===Member types===
{{dsc begin}}
{{dsc hitem|Member type|Definition}}
{{dsc inc|cpp/container/dsc key_container_type|flat_map}}
{{dsc inc|cpp/container/dsc mapped_container_type|flat_map}}
{{dsc inc|cpp/container/dsc key_type|flat_map}}
{{dsc inc|cpp/container/dsc mapped_type|flat_map}}
{{dsc inc|cpp/container/dsc value_type|flat_map}}
{{dsc inc|cpp/container/dsc key_compare|flat_map}}
{{dsc inc|cpp/container/dsc reference|flat_map}}
{{dsc inc|cpp/container/dsc const_reference|flat_map}}
{{dsc inc|cpp/container/dsc size_type|flat_map}}
{{dsc inc|cpp/container/dsc difference_type|flat_map}}
{{dsc inc|cpp/container/dsc iterator|flat_map}}
{{dsc inc|cpp/container/dsc const_iterator|flat_map}}
{{dsc inc|cpp/container/dsc reverse_iterator|flat_map}}
{{dsc inc|cpp/container/dsc const_reverse_iterator|flat_map}}
{{dsc inc|cpp/container/dsc containers|flat_map}}
{{dsc end}}

===Member classes===
{{dsc begin}}
{{dsc inc|cpp/container/dsc value_compare|flat_map}}<!--
{{dsc inc|cpp/container/dsc key_equiv|flat_map}}-->
{{dsc end}}

===Member objects===
{{dsc begin}}
{{dsc hitem|Member name|Definition}}
{{dsc expos mem obj|private=yes|c|the object of type {{tt|containers}}}}
{{dsc expos mem obj|private=yes|compare|the comparison function object of type {{tt|key_compare}}}}
{{dsc end}}

===Member functions===
{{dsc begin}}
{{dsc inc|cpp/container/dsc constructor|flat_map}}
{{dsc mem dtor|nolink=true|notes={{mark implicit}}|destroys every element of the container adaptor}}
{{dsc inc|cpp/container/dsc operator{{=}}|flat_map}}

{{dsc h2|Element access}}
{{dsc inc|cpp/container/dsc at|flat_map}}
{{dsc inc|cpp/container/dsc operator_at|flat_map}}

{{dsc h2|Iterators}}
{{dsc inc|cpp/container/dsc begin|flat_map}}
{{dsc inc|cpp/container/dsc end|flat_map}}
{{dsc inc|cpp/container/dsc rbegin|flat_map}}
{{dsc inc|cpp/container/dsc rend|flat_map}}

{{dsc h2|Capacity}}
{{dsc inc|cpp/container/dsc empty|flat_map}}
{{dsc inc|cpp/container/dsc size|flat_map}}
{{dsc inc|cpp/container/dsc max_size|flat_map}}

{{dsc h2|Modifiers}}
{{dsc inc|cpp/container/dsc emplace|flat_map}}
{{dsc inc|cpp/container/dsc emplace_hint|flat_map}}
{{dsc inc|cpp/container/dsc try_emplace|flat_map}}
{{dsc inc|cpp/container/dsc insert|flat_map}}
{{dsc inc|cpp/container/dsc insert_range|flat_map}}
{{dsc inc|cpp/container/dsc insert_or_assign|flat_map}}
{{dsc inc|cpp/container/dsc extract|flat_map}}
{{dsc inc|cpp/container/dsc replace|flat_map}}
{{dsc inc|cpp/container/dsc erase|flat_map}}
{{dsc inc|cpp/container/dsc swap|flat_map}}
{{dsc inc|cpp/container/dsc clear|flat_map}}

{{dsc h2|Lookup}}
{{dsc inc|cpp/container/dsc find|flat_map}}
{{dsc inc|cpp/container/dsc count|flat_map}}
{{dsc inc|cpp/container/dsc contains|flat_map}}
{{dsc inc|cpp/container/dsc lower_bound|flat_map}}
{{dsc inc|cpp/container/dsc upper_bound|flat_map}}
{{dsc inc|cpp/container/dsc equal_range|flat_map}}

{{dsc h2|Observers}}
{{dsc inc|cpp/container/dsc key_comp|flat_map}}
{{dsc inc|cpp/container/dsc value_comp|flat_map}}
{{dsc inc|cpp/container/dsc keys|flat_map}}
{{dsc inc|cpp/container/dsc values|flat_map}}
{{dsc end}}

===Non-member functions===
{{dsc begin}}
{{dsc inc|cpp/container/dsc operator_cmp|flat_map}}
{{dsc inc|cpp/container/dsc swap2|flat_map}}
{{dsc inc|cpp/container/dsc erase_if|flat_map}}
{{dsc end}}

===Helper classes===
{{dsc begin}}
{{dsc inc|cpp/container/dsc uses_allocator|flat_map}}
{{dsc end}}

===Tags===
{{dsc begin}}
{{dsc inc|cpp/container/dsc sorted_unique}}
{{dsc end}}

==={{rl|deduction guides|Deduction guides}}===

===Notes===
{{cpp/container/assoc_note}}<!-- TODO: is this relevant to flat_map? -->

<!-- TODO: maybe this lyrics is unnecessary:
Some advantages of flat map over other standard [[associative containers]] are:
* Potentially faster lookup (even though search operations have logarithmic complexity).
* Much faster iteration: {{lt|cpp/iterator/random access iterator}}s instead of {{lt|cpp/iterator/bidirectional iterator}}s.
* Less memory consumption for small objects (and for big objects if {{c|KeyContainer::shrink_to_fit()}} is available).
* Better cache performance (depending on {{tt|KeyContainer}}, keys are stored in a contiguous block(s) of memory).

Some disadvantages of flat map are:
* Non-stable iterators (iterators are invalidated when inserting and erasing elements).
* Non-copyable and non-movable type values can not be stored.
* Weaker exception safety (copy/move constructors can throw when shifting values in erasures and insertions).
* Slower (i.e. linear) insertion and erasure, especially for non-movable types.
-->

{{ftm begin}}
{{ftm|__cpp_lib_flat_map|value=202207L|std=C++23|{{tt|std::flat_map}} and {{lc|std::flat_multimap}}}}
{{ftm end}}

===Example===
{{example}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/container/dsc flat_multimap}}
{{dsc inc|cpp/container/dsc map}}
{{dsc inc|cpp/container/dsc unordered_map}}
{{dsc end}}

{{langlinks|cs|de|es|fr|it|ja|pl|pt|ru|zh}}

<!--TODO: N4950::24.6.9 says:
TODO: add this to the "Exceptions" sections of appropriate member functions:
6. If any member function in 24.6.9.2 exits via an exception, the invariants are restored.
[Note 2 : This can result in the flat_map’s being emptied. — end note].
-->

<!--TODO: N4950::24.6.9.1 says:
TODO: add to constructors:
9. The effect of calling a constructor that takes both key_container_type and mapped_container_type arguments with containers of different sizes is undefined.
10. The effect of calling a constructor or member function that takes a sorted_unique_t argument with a container, containers, or range that is not sorted with respect to key_comp(), or that contains equal elements, is undefined.
-->

<!-- TODO: also complete [[cpp/container#Iterator invalidation]] table for flat_* adaptors -->