add extract() and replace() to flat_map (#1078)

Author: suomesta

reference/flat_map/flat_map.md

@@ -66,8 +66,8 @@ namespace std {
 | [`try_emplace`](flat_map/try_emplace.md)           | キーが存在しない場合のみ要素を直接構築する | C++23 |
 | [`erase`](flat_map/erase.md)                       | 要素を削除する                             | C++23 |
 | [`swap`](flat_map/swap.md)                         | コンテンツを交換する                       | C++23 |
-| [`extract`](flat_map/extract.md.nolink)                   | キーのコンテナ、値のコンテナを取得する     | C++23 |
-| [`replace`](flat_map/replace.md.nolink)                   | キーのコンテナ、値のコンテナを置き換える   | C++23 |
+| [`extract`](flat_map/extract.md)                   | キーのコンテナ、値のコンテナを取得する     | C++23 |
+| [`replace`](flat_map/replace.md)                   | キーのコンテナ、値のコンテナを置き換える   | C++23 |
 
 
 ### 要素アクセス

reference/flat_map/flat_map/containers.md

@@ -29,7 +29,7 @@ namespace std {
 ## 概要
 `flat_map`クラス内部のデータ保持方法として、キーのコンテナと値のコンテナをもつ。
 
-この形式の内部表現は[`extract()`](extract.md.nolink)メンバ関数で取得でき、シリアライズなどの用途に使用できる。
+この形式の内部表現は [`extract()`](extract.md) メンバ関数で取得でき、シリアライズなどの用途に使用できる。
 
 
 ## 例
@@ -38,6 +38,7 @@ namespace std {
 #include <iostream>
 #include <flat_map>
 #include <string>
+#include <utility>
 
 int main()
 {
@@ -47,21 +48,21 @@ int main()
     {"Carol", 4}
   };
 
-  decltype(fm)::containers c = fm.extract();
+  decltype(fm)::containers c = std::move(fm).extract();
 
-  std::cout << "keys:"
+  std::cout << "keys:" << std::endl;
   for (const auto& key : c.keys) {
     std::cout << "  " << key << std::endl;
   }
 
-  std::cout << "values:"
+  std::cout << "values:" << std::endl;
   for (const auto& value : c.values) {
     std::cout << "  " << value << std::endl;
   }
 }
 ```
 * containers[color ff0000]
-* fm.extract()[link extract.md.nolink]
+* fm.extract()[link extract.md]
 
 #### 出力
 ```
@@ -84,3 +85,7 @@ values:
 - [Clang](/implementation.md#clang): ??
 - [GCC](/implementation.md#gcc): ??
 - [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`extract`](extract.md)

reference/flat_map/flat_map/extract.md

@@ -0,0 +1,90 @@
+# extract
+* flat_map[meta header]
+* std[meta namespace]
+* flat_map[meta class]
+* function[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+containers extract() &&;  // C++23
+```
+
+## 概要
+キーのコンテナ、値のコンテナを戻り値として返す。
+
+
+## 戻り値
+クラス内部のデータ保持形式である [`containers`](containers.md) オブジェクト。
+
+
+## 事後条件
+呼び出し側の `flat_map` は空になる（たとえ例外で関数が中断されたとしても）。
+
+
+## 計算量
+定数時間。
+
+
+## 備考
+本関数は右辺値修飾されているので、右辺値からのみ読み出し可能である。
+
+
+## 例
+```cpp example
+#include <flat_map>
+#include <iostream>
+#include <string>
+#include <utility>
+
+int main()
+{
+  std::flat_map<std::string, int> fm = {
+    {"Alice", 3},
+    {"Bob",   1},
+    {"Carol", 4}
+  };
+
+  std::cout << fm.size() << std::endl;
+
+  decltype(fm)::containers c = std::move(fm).extract();
+
+  std::cout << fm.size() << std::endl;
+  std::cout << std::endl;
+
+  auto k = c.keys.cbegin();
+  auto v = c.values.cbegin();
+  std::cout << "{" << std::endl;
+  for (; k != c.keys.cend() && v != c.values.cend(); ++k, ++v) {
+    std::cout << "  " << *k << ": " << *v << "," << std::endl;
+  }
+  std::cout << "}" << std::endl;
+}
+```
+* extract()[color ff0000]
+* fm.size()[link size.md]
+
+### 出力
+```
+3
+0
+
+{
+  Alice: 3,
+  Bob: 1,
+  Carol: 4,
+}
+```
+
+## バージョン
+### 言語
+- C++23
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`containers`](containers.md)

reference/flat_map/flat_map/replace.md

@@ -0,0 +1,94 @@
+# replace
+* flat_map[meta header]
+* std[meta namespace]
+* flat_map[meta class]
+* function[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+void replace(key_container_type&& key_cont, mapped_container_type&& mapped_cont);  // C++23
+```
+
+## 概要
+キーのコンテナ、値のコンテナをそれぞれ置き換える。
+
+
+## 効果
+`flat_map` クラスが内部で保持している [`containers`](containers.md) を `c` とすると、以下と等価。
+    ```cpp
+    c.keys = std::move(key_cont);
+    c.values = std::move(mapped_cont)
+    ```
+
+
+## 事前条件
+- `key_cont.size() == mapped_cont.size()` が真であること。
+- `key_cont` が `key_compare` に基づいてソートされていること。
+- `key_cont` に重複する要素がないこと。
+
+
+## 計算量
+`key_cont` および `mapped_cont` をムーブした計算量と同じ。
+
+
+## 例
+```cpp example
+#include <algorithm>
+#include <cassert>
+#include <flat_map>
+#include <iostream>
+#include <string>
+#include <utility>
+
+int main()
+{
+  std::vector<std::string> keys = {"Alice", "Bob", "Carol"};
+  std::vector<int> values = {3, 1, 4};
+
+  // 事前条件の確認
+  assert(keys.size() == values.size());
+  assert(std::is_sorted(keys.begin(), keys.end()));
+  assert(std::adjacent_find(keys.begin(), keys.end()) == keys.end());
+
+  std::flat_map<std::string, int> fm;
+
+  std::cout << fm.size() << std::endl;
+
+  fm.replace(std::move(keys), std::move(values));
+
+  std::cout << fm.size() << std::endl;
+  std::cout << std::endl;
+
+  std::cout << "{" << std::endl;
+  for (const auto& kv: fm) {
+    std::cout << "  " << kv.first << ": " << kv.second << "," << std::endl;
+  }
+  std::cout << "}" << std::endl;
+}
+```
+* replace[color ff0000]
+* fm.size()[link size.md]
+* std::is_sorted[link /reference/algorithm/is_sorted.md]
+* std::adjacent_find[link /reference/algorithm/adjacent_find.md]
+
+### 出力
+```
+0
+3
+
+{
+  Alice: 3,
+  Bob: 1,
+  Carol: 4,
+}
+```
+
+## バージョン
+### 言語
+- C++23
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??