[flat.map.modifiers] - C++20 → C++23

Files changed (1) hide show

tmp/tmpisuy6fzx/{from.md → to.md} +318 -0

tmp/tmpisuy6fzx/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,318 @@

+#### Modifiers <a id="flat.map.modifiers">[[flat.map.modifiers]]</a>
+``` cpp
+template<class... Args> pair<iterator, bool> emplace(Args&&... args);
+```
+*Constraints:*
+`is_constructible_v<pair<key_type, mapped_type>, Args...>` is `true`.
+*Effects:* Initializes an object `t` of type
+`pair<key_type, mapped_type>` with `std::forward<Args>(args)...`; if the
+map already contains an element whose key is equivalent to `t.first`,
+`*this` is unchanged. Otherwise, equivalent to:
+``` cpp
+auto key_it = ranges::upper_bound(c.keys, t.first, compare);
+auto value_it = c.values.begin() + distance(c.keys.begin(), key_it);
+c.keys.insert(key_it, std::move(t.first));
+c.values.insert(value_it, std::move(t.second));
+```
+*Returns:* The `bool` component of the returned pair is `true` if and
+only if the insertion took place, and the iterator component of the pair
+points to the element with key equivalent to `t.first`.
+``` cpp
+template<class P> pair<iterator, bool> insert(P&& x);
+template<class P> iterator insert(const_iterator position, P&& x);
+```
+*Constraints:* `is_constructible_v<pair<key_type, mapped_type>, P>` is
+`true`.
+*Effects:* The first form is equivalent to
+`return emplace(std::forward<P>(x));`. The second form is equivalent to
+`return emplace_hint(position, std::forward<P>(x));`.
+``` cpp
+template<class InputIterator>
+  void insert(InputIterator first, InputIterator last);
+```
+*Effects:* Adds elements to `c` as if by:
+``` cpp
+for (; first != last; ++first) {
+  value_type value = *first;
+  c.keys.insert(c.keys.end(), std::move(value.first));
+  c.values.insert(c.values.end(), std::move(value.second));
+}
+```
+Then, sorts the range of newly inserted elements with respect to
+`value_comp()`; merges the resulting sorted range and the sorted range
+of pre-existing elements into a single sorted range; and finally erases
+the duplicate elements as if by:
+``` cpp
+auto zv = ranges::zip_view(c.keys, c.values);
+auto it = ranges::unique(zv, key_equiv(compare)).begin();
+auto dist = distance(zv.begin(), it);
+c.keys.erase(c.keys.begin() + dist, c.keys.end());
+c.values.erase(c.values.begin() + dist, c.values.end());
+```
+*Complexity:* N + M log M, where N is `size()` before the operation and
+M is `distance(first, last)`.
+*Remarks:* Since this operation performs an in-place merge, it may
+allocate memory.
+``` cpp
+template<class InputIterator>
+  void insert(sorted_unique_t, InputIterator first, InputIterator last);
+```
+*Effects:* Adds elements to `c` as if by:
+``` cpp
+for (; first != last; ++first) {
+  value_type value = *first;
+  c.keys.insert(c.keys.end(), std::move(value.first));
+  c.values.insert(c.values.end(), std::move(value.second));
+}
+```
+Then, merges the sorted range of newly added elements and the sorted
+range of pre-existing elements into a single sorted range; and finally
+erases the duplicate elements as if by:
+``` cpp
+auto zv = ranges::zip_view(c.keys, c.values);
+auto it = ranges::unique(zv, key_equiv(compare)).begin();
+auto dist = distance(zv.begin(), it);
+c.keys.erase(c.keys.begin() + dist, c.keys.end());
+c.values.erase(c.values.begin() + dist, c.values.end());
+```
+*Complexity:* Linear in N, where N is `size()` after the operation.
+*Remarks:* Since this operation performs an in-place merge, it may
+allocate memory.
+``` cpp
+template<container-compatible-range<value_type> R>
+  void insert_range(R&& rg);
+```
+*Effects:* Adds elements to `c` as if by:
+``` cpp
+for (const auto& e : rg) {
+  c.keys.insert(c.keys.end(), e.first);
+  c.values.insert(c.values.end(), e.second);
+}
+```
+Then, sorts the range of newly inserted elements with respect to
+`value_comp()`; merges the resulting sorted range and the sorted range
+of pre-existing elements into a single sorted range; and finally erases
+the duplicate elements as if by:
+``` cpp
+auto zv = ranges::zip_view(c.keys, c.values);
+auto it = ranges::unique(zv, key_equiv(compare)).begin();
+auto dist = distance(zv.begin(), it);
+c.keys.erase(c.keys.begin() + dist, c.keys.end());
+c.values.erase(c.values.begin() + dist, c.values.end());
+```
+*Complexity:* N + M log M, where N is `size()` before the operation and
+M is `ranges::distance(rg)`.
+*Remarks:* Since this operation performs an in-place merge, it may
+allocate memory.
+``` cpp
+template<class... Args>
+  pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
+template<class... Args>
+  pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
+template<class... Args>
+  iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);
+template<class... Args>
+  iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
+```
+*Constraints:* `is_constructible_v<mapped_type, Args...>` is `true`.
+*Effects:* If the map already contains an element whose key is
+equivalent to `k`, `*this` and `args...` are unchanged. Otherwise
+equivalent to:
+``` cpp
+auto key_it = ranges::upper_bound(c.keys, k, compare);
+auto value_it = c.values.begin() + distance(c.keys.begin(), key_it);
+c.keys.insert(key_it, std::forward<decltype(k)>(k));
+c.values.emplace(value_it, std::forward<Args>(args)...);
+```
+*Returns:* In the first two overloads, the `bool` component of the
+returned pair is `true` if and only if the insertion took place. The
+returned iterator points to the map element whose key is equivalent to
+`k`.
+*Complexity:* The same as `emplace` for the first two overloads, and the
+same as `emplace_hint` for the last two overloads.
+``` cpp
+template<class K, class... Args>
+  pair<iterator, bool> try_emplace(K&& k, Args&&... args);
+template<class K, class... Args>
+  iterator try_emplace(const_iterator hint, K&& k, Args&&... args);
+```
+*Constraints:*
+- The *qualified-id* `Compare::is_transparent` is valid and denotes a
+  type.
+- `is_constructible_v<key_type, K>` is `true`.
+- `is_constructible_v<mapped_type, Args...>` is `true`.
+- For the first overload, `is_convertible_v<K&&, const_iterator>` and
+  `is_convertible_v<K&&, iterator>` are both `false`.
+*Preconditions:* The conversion from `k` into `key_type` constructs an
+object `u`, for which `find(k) == find(u)` is `true`.
+*Effects:* If the map already contains an element whose key is
+equivalent to `k`, `*this` and `args...` are unchanged. Otherwise
+equivalent to:
+``` cpp
+auto key_it = ranges::upper_bound(c.keys, k, compare);
+auto value_it = c.values.begin() + distance(c.keys.begin(), key_it);
+c.keys.emplace(key_it, std::forward<K>(k));
+c.values.emplace(value_it, std::forward<Args>(args)...);
+```
+*Returns:* In the first overload, the `bool` component of the returned
+pair is `true` if and only if the insertion took place. The returned
+iterator points to the map element whose key is equivalent to `k`.
+*Complexity:* The same as `emplace` and `emplace_hint`, respectively.
+``` cpp
+template<class M>
+  pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
+template<class M>
+  pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
+template<class M>
+  iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
+template<class M>
+  iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);
+```
+*Constraints:* `is_assignable_v<mapped_type&, M>` is `true` and
+`is_constructible_v<mapped_type, M>` is `true`.
+*Effects:* If the map already contains an element `e` whose key is
+equivalent to `k`, assigns `std::forward<M>(obj)` to `e.second`.
+Otherwise, equivalent to
+``` cpp
+try_emplace(std::forward<decltype(k)>(k), std::forward<M>(obj))
+```
+for the first two overloads or
+``` cpp
+try_emplace(hint, std::forward<decltype(k)>(k), std::forward<M>(obj))
+```
+for the last two overloads.
+*Returns:* In the first two overloads, the `bool` component of the
+returned pair is `true` if and only if the insertion took place. The
+returned iterator points to the map element whose key is equivalent to
+`k`.
+*Complexity:* The same as `emplace` for the first two overloads and the
+same as `emplace_hint` for the last two overloads.
+``` cpp
+template<class K, class M>
+  pair<iterator, bool> insert_or_assign(K&& k, M&& obj);
+template<class K, class M>
+  iterator insert_or_assign(const_iterator hint, K&& k, M&& obj);
+```
+*Constraints:*
+- The *qualified-id* `Compare::is_transparent` is valid and denotes a
+  type.
+- `is_constructible_v<key_type, K>` is `true`.
+- `is_assignable_v<mapped_type&, M>` is `true`.
+- `is_constructible_v<mapped_type, M>` is `true`.
+*Preconditions:* The conversion from `k` into `key_type` constructs an
+object `u`, for which `find(k) == find(u)` is `true`.
+*Effects:* If the map already contains an element `e` whose key is
+equivalent to `k`, assigns `std::forward<M>(obj)` to `e.second`.
+Otherwise, equivalent to
+``` cpp
+try_emplace(std::forward<K>(k), std::forward<M>(obj))
+```
+for the first overload or
+``` cpp
+try_emplace(hint, std::forward<K>(k), std::forward<M>(obj))
+```
+for the second overload.
+*Returns:* In the first overload, the `bool` component of the returned
+pair is `true` if and only if the insertion took place. The returned
+iterator points to the map element whose key is equivalent to `k`.
+*Complexity:* The same as `emplace` and `emplace_hint`, respectively.
+``` cpp
+void swap(flat_map& y) noexcept;
+```
+*Effects:* Equivalent to:
+``` cpp
+ranges::swap(compare, y.compare);
+ranges::swap(c.keys, y.c.keys);
+ranges::swap(c.values, y.c.values);
+```
+``` cpp
+containers extract() &&;
+```
+*Ensures:* `*this` is emptied, even if the function exits via an
+exception.
+*Returns:* `std::move(c)`.
+``` cpp
+void replace(key_container_type&& key_cont, mapped_container_type&& mapped_cont);
+```
+*Preconditions:* `key_cont.size() == mapped_cont.size()` is `true`, the
+elements of `key_cont` are sorted with respect to `compare`, and
+`key_cont` contains no equal elements.
+*Effects:* Equivalent to:
+``` cpp
+c.keys = std::move(key_cont);
+c.values = std::move(mapped_cont);
+```

Diff to HTML by rtfpessoa