map::insert_or_assign : C++26の異種混合ルックアップに対応 #1189

Author: faithandbrave

reference/map/map/at.md

@@ -104,6 +104,5 @@ exception std::out_of_range
 
 ## 参照
 - [LWG Issue 464. Suggestion for new member functions in standard containers](http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#464)
-## 参照
 - [P2363R5 Extending associative containers with the remaining heterogeneous overloads](http://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2363r5.html)
     - C++26で`template <class K>`のバージョンが追加された

reference/map/map/insert_or_assign.md

@@ -7,16 +7,33 @@
 
 ```cpp
 template <class M>
-pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);              // (1)
-
+pair<iterator, bool>
+  insert_or_assign(const key_type& k,
+                   M&& obj);          // (1) C++17
 template <class M>
-pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);                   // (2)
-
+pair<iterator, bool>
+  insert_or_assign(key_type&& k,
+                   M&& obj);          // (2) C++17
 template <class M>
-iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);     // (3)
-
+iterator
+  insert_or_assign(const_iterator hint,
+                   const key_type& k,
+                   M&& obj);          // (3) C++17
 template <class M>
-iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);          // (4)
+iterator
+  insert_or_assign(const_iterator hint,
+                   key_type&& k,
+                   M&& obj);          // (4) C++17
+
+template <class K, class M>
+pair<iterator, bool>
+  insert_or_assign(K&& k,
+                   M&& obj);          // (5) C++26
+template <class K, class M>
+iterator
+  insert_or_assign(const_iterator hint,
+                   K&& k,
+                   M&& obj);          // (6) C++26
 ```
 * pair[link /reference/utility/pair.md]
 
@@ -29,40 +46,44 @@ iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);
 - (2) : `key_type`型の一時オブジェクトのキーをとって挿入もしくは代入する
 - (3) : 挿入位置のヒントをともない、`key_type`型のキーをとって挿入もしくは代入する
 - (4) : 挿入位置のヒントをともない、`key_type`型の一時オブジェクトのキーをとって挿入もしくは代入する
+- (5) : `key_type`と比較可能な`K`型のキーをとって挿入もしくは代入する
+- (6) : 挿入位置のヒントをともない、`key_type`と比較可能な`K`型のキーをとって挿入もしくは代入する
 
 
 ## テンプレートパラメータ制約
-- (1)、(3) : [`is_assignable_v`](/reference/type_traits/is_assignable.md)`<mapped_type&, M&&>` が `true` であること。`value_type` は、`k`, [`forward`](/reference/utility/forward.md)`<M>(obj)` から `map` に直接構築可能であること
+- (5), (6) : `key_compare::is_transparent` が妥当な式であること
+
+
+## 適格要件
+- (1)、(3)、(5)、(6) : [`is_assignable_v`](/reference/type_traits/is_assignable.md)`<mapped_type&, M&&>` が `true` であること。`value_type` は、`k`, [`forward`](/reference/utility/forward.md)`<M>(obj)` から `map` に直接構築可能であること
 - (2)、(4) : [`is_assignable_v`](/reference/type_traits/is_assignable.md)`<mapped_type&, M&&>` が `true` であること。`value_type` は、[`move`](/reference/utility/move.md)`(k)`, [`forward`](/reference/utility/forward.md)`<M>(obj)` から `map` に直接構築可能であること
 
 なお、規格に記載はないが、`hint` は [`emplace_hint`](emplace_hint.md) と同様、コンテナの有効な読み取り専用イテレータである必要があるものと思われる。
 
 
 ## 効果
-- (1)、(3) : `map` が `k` と同値のキーを持つ要素 `e` を持っている場合、`e.second` に [`forward`](/reference/utility/forward.md)`<M>(obj)` を代入する。そうでなければ、`k`, [`forward`](/reference/utility/forward.md)`<M>(obj)` から構築した `value_type` 型のオブジェクトを挿入する。
+- (1)、(3)、(5)、(6) : `map` が `k` と同値のキーを持つ要素 `e` を持っている場合、`e.second` に [`forward`](/reference/utility/forward.md)`<M>(obj)` を代入する。そうでなければ、`k`, [`forward`](/reference/utility/forward.md)`<M>(obj)` から構築した `value_type` 型のオブジェクトを挿入する。
 - (2)、(4) : `map` が `k` と同値のキーを持つ要素 `e` を持っている場合、`e.second` に [`forward`](/reference/utility/forward.md)`<M>(obj)` を代入する。そうでなければ、[`move`](/reference/utility/move.md)`(k)`, [`forward`](/reference/utility/forward.md)`<M>(obj)` から構築した `value_type` 型のオブジェクトを挿入する。
 
 
 ## 戻り値
-- (1)、(2) : イテレータと `bool` 値の [`pair`](/reference/utility/pair.md) を返す。
+- (1)、(2)、(5) : イテレータと `bool` 値の [`pair`](/reference/utility/pair.md) を返す。
     - 挿入された場合には、`first` に挿入された要素へのイテレータ、`second` に `true` が設定される。
     - 代入された場合には、`first` に代入された要素へのイテレータ、`second` に `false` が設定される。
-- (3)、(4) :
+- (3)、(4)、(6) :
     - 挿入された場合には、挿入された要素へのイテレータを返す。
     - 代入された場合には、代入された要素へのイテレータを返す。
 
 
 ## 計算量
-- (1)、(2) : [`emplace`](emplace.md) と同じ。
-- (3)、(4) : [`emplace_hint`](emplace_hint.md) と同じ。
+- (1)、(2)、(5) : [`emplace`](emplace.md) と同じ。
+- (3)、(4)、(6) : [`emplace_hint`](emplace_hint.md) と同じ。
 
 
 ## 備考
-このメンバ関数の機能テストマクロは以下の通り。
-
-| マクロ名                    | 値       |
-|-----------------------------|----------|
-| `__cpp_lib_map_try_emplace` | `201411` |
+- (5), (6) :
+    - `is_transparent`は、標準ライブラリの[`std::less`](/reference/functional/less.md)、[`std::greater`](/reference/functional/greater.md)といった関数オブジェクトの、`void`に対する特殊化で定義される。それ以外のテンプレートパラメータで`is_transparent`が定義されないのは、互換性のためである。
+    - これらのオーバーロードは、`map<string, int>`のようなコンテナに対し、検索操作で文字列リテラルを渡した際に、キー型の一時オブジェクトが生成されるコストを減らすためにある。
 
 
 ## 例
@@ -116,3 +137,5 @@ int main()
 - [N4006 An improved emplace() for unique-key maps](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4006.html)
 - [N4240 Improved insertion interface for unique-key maps (Revision 2)](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4240.html)
 - [N4279 Improved insertion interface for unique-key maps (Revision 2.3)](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4279.html)
+- [P2363R5 Extending associative containers with the remaining heterogeneous overloads](http://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2363r5.html)
+    - C++26で`template <class K>`のバージョンが追加された