Difference between revisions of "cpp/container/flat map"
From cppreference.com
m (+page, early draft.) |
m (fmt.) |
||
| (6 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{cpp/title|flat_map}} | {{cpp/title|flat_map}} | ||
{{cpp/container/flat_map/navbar}} | {{cpp/container/flat_map/navbar}} | ||
| − | {{ddcl|header=flat_map| | + | {{ddcl|header=flat_map|since=c++23|1= |
template< | template< | ||
class Key, | class Key, | ||
| Line 17: | Line 17: | ||
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)}}. | 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}}, | + | {{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, | * requirements related to nodes are not applicable, | ||
* iterator invalidation requirements differ, <!--TODO: describe iterator/pointer invalidation properties, maybe per each function, in their pages --> | * iterator invalidation requirements differ, <!--TODO: describe iterator/pointer invalidation properties, maybe per each function, in their pages --> | ||
| Line 31: | Line 31: | ||
{{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|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|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|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. | {{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. | ||
| Line 38: | Line 38: | ||
===Member types=== | ===Member types=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc hitem| | + | {{dsc hitem|Type|Definition}} |
{{dsc inc|cpp/container/dsc key_container_type|flat_map}} | {{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 mapped_container_type|flat_map}} | ||
| Line 64: | Line 64: | ||
===Member objects=== | ===Member objects=== | ||
{{dsc begin}} | {{dsc begin}} | ||
| − | {{dsc hitem|Member | + | {{dsc hitem|Member|Description}} |
| − | {{dsc expos mem obj|private=yes| | + | {{dsc expos mem obj|c|id=c|private=yes|spec={{tt|containers}}|the adapted containers}} |
| − | {{dsc expos mem obj|private=yes| | + | {{dsc expos mem obj|compare|id=compare|private=yes|spec={{tt|key_compare}}|the comparison function object}} |
{{dsc end}} | {{dsc end}} | ||
| Line 72: | Line 72: | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc inc|cpp/container/dsc constructor|flat_map}} | {{dsc inc|cpp/container/dsc constructor|flat_map}} | ||
| − | {{dsc | + | {{dsc mem dtor|nolink=true|notes={{mark implicit}}|destroys every element of the container adaptor}} |
{{dsc inc|cpp/container/dsc operator{{=}}|flat_map}} | {{dsc inc|cpp/container/dsc operator{{=}}|flat_map}} | ||
| Line 133: | Line 133: | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc inc|cpp/container/dsc sorted_unique}} | {{dsc inc|cpp/container/dsc sorted_unique}} | ||
| − | |||
{{dsc end}} | {{dsc end}} | ||
| Line 173: | Line 172: | ||
<!--TODO: N4950::24.6.9 says: | <!--TODO: N4950::24.6.9 says: | ||
TODO: add this to the "Exceptions" sections of appropriate member functions: | 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 | + | 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]. | [Note 2 : This can result in the flat_map’s being emptied. — end note]. | ||
--> | --> | ||
Latest revision as of 14:46, 1 November 2024
| Defined in header <flat_map>
|
||
| template< class Key, |
(since C++23) | |
The flat map is a 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 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 Compare 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 Container, ReversibleContainer, optional container requirements, and all requirements of AssociativeContainer (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 AssociativeContainer's operations that use unique keys.
Contents |
[edit] Iterator invalidation
| This section is incomplete |
[edit] 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 Compare type providing a strict weak ordering. |
| KeyContainer MappedContainer |
- | The types of the underlying SequenceContainer to store keys and mapped values correspondingly. The iterators of such containers should satisfy LegacyRandomAccessIterator or model random_access_iterator. Invocations of their member functions size and max_size should not exit via an exception.
The standard containers std::vector and std::deque satisfy these requirements. |
[edit] Member types
| Type | Definition |
key_container_type
|
KeyContainer
|
mapped_container_type
|
MappedContainer
|
key_type
|
Key
|
mapped_type
|
T
|
value_type
|
std::pair<key_type, mapped_type> |
key_compare
|
Compare
|
reference
|
std::pair<const key_type&, mapped_type&> |
const_reference
|
std::pair<const key_type&, const mapped_type&> |
size_type
|
std::size_t |
difference_type
|
std::ptrdiff_t |
iterator
|
implementation-defined LegacyInputIterator and random_access_iterator to value_type
|
const_iterator
|
implementation-defined LegacyInputIterator and random_access_iterator to const value_type
|
reverse_iterator
|
std::reverse_iterator<iterator> |
const_reverse_iterator
|
std::reverse_iterator<const_iterator> |
containers
|
type describing the underlying containers struct containers |
[edit] Member classes
compares objects of type value_type (class) |
[edit] Member objects
| Member | Description |
containers c (private)
|
the adapted containers (exposition-only member object*) |
key_compare compare (private)
|
the comparison function object (exposition-only member object*) |
[edit] 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) | |
[edit] Non-member functions
| (C++23) |
lexicographically compares the values of two flat_maps (function template) |
| (C++23) |
specializes the std::swap algorithm (function template) |
| (C++23) |
erases all elements satisfying specific criteria (function template) |
[edit] Helper classes
| specializes the std::uses_allocator type trait (class template specialization) |
[edit] Tags
| (C++23) |
indicates that elements of a range are sorted and unique (tag) |
[edit] Deduction guides
[edit] 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 One Definition Rule. Since iterator is convertible to const_iterator, a single function with a const_iterator as parameter type will work instead.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_flat_map |
202207L | (C++23) | std::flat_map and std::flat_multimap
|
[edit] Example
| This section is incomplete Reason: no example |
[edit] 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) |
