flat_map : lower_bound, upper_bound, equal_rangeを追加 #1078

reference/flat_map/flat_map.md

@@ -79,9 +79,9 @@ namespace std {
 | [`count`](flat_map/count.md)             | 指定したキーにマッチする要素の数を取得する | C++23 |
 | [`find`](flat_map/find.md)               | 指定したキーで要素を探す                   | C++23 |
 | [`contains`](flat_map/contains.md)       | 指定したキーの要素が含まれているかを判定する | C++23 |
-| [`equal_range`](flat_map/equal_range.md.nolink) | 指定したキーにマッチする要素範囲を取得する | C++23 |
-| [`lower_bound`](flat_map/lower_bound.md.nolink) | 与えられた値より小さくない最初の要素へのイテレータを取得する | C++23 |
-| [`upper_bound`](flat_map/upper_bound.md.nolink) | 特定の値よりも大きい最初の要素へのイテレータを取得する       | C++23 |
+| [`equal_range`](flat_map/equal_range.md) | 指定したキーにマッチする要素範囲を取得する | C++23 |
+| [`lower_bound`](flat_map/lower_bound.md) | 与えられた値より小さくない最初の要素へのイテレータを取得する | C++23 |
+| [`upper_bound`](flat_map/upper_bound.md) | 特定の値よりも大きい最初の要素へのイテレータを取得する       | C++23 |
 
 ### オブザーバー
 

reference/flat_map/flat_map/equal_range.md

@@ -0,0 +1,85 @@
+# equal_range
+* flat_map[meta header]
+* std[meta namespace]
+* flat_map[meta class]
+* function[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+pair<iterator, iterator> equal_range(const key_type& x); // (1) C++23
+
+template <class K>
+pair<iterator, iterator> equal_range(const K& x);        // (2) C++23
+
+pair<const_iterator, const_iterator>
+  equal_range(const key_type& x) const;                  // (3) C++23
+
+template <class K>
+pair<const_iterator, const_iterator>
+  equal_range(const K& x) const;                         // (4) C++23
+```
+* pair[link /reference/utility/pair.md]
+
+## 概要
+コンテナ内の、`x` と等しいキー要素を全て含む範囲の境界を返す。`map` コンテナではキーの重複は無いため、この範囲は最大一つの要素を含む。 
+
+もし `x` がコンテナ内のどのキーともマッチしなかった場合、戻り値の範囲は長さ 0 になり、両方のイテレータは `x` より大きく最も近い値を指す。そうでない場合、`x` がコンテナ内の全ての要素よりも大きい場合は [`end`](end.md) を指す。
+
+- (1) : `key_type`型のキーを受け取り、そのキーと等価なキー要素を全て含むイテレータ範囲を取得する。
+- (2) : `key_type`と比較可能な`K`型のキーを受け取り、そのキーと等価なキー要素を全て含むイテレータ範囲を取得する。
+- (3) : `const`な`*this`オブジェクトにおいて、`key_type`型のキーを受け取り、そのキーと等価なキー要素を全て含むイテレータ範囲を取得する。
+- (4) : `const`な`*this`オブジェクトにおいて、`key_type`と比較可能な`K`型のキーを受け取り、そのキーと等価なキー要素を全て含むイテレータ範囲を取得する。
+
+
+## 戻り値
+この関数は `pair` を返す。ここで `pair::first` は [`lower_bound`](lower_bound.md)`(x)` が返すであろう値と同じ値で範囲の下境界にあたり、`pair::second` は [`upper_bound`](upper_bound.md)`(x)` が返すであろう値と同じ値で範囲の上境界にあたる。
+
+
+## 計算量
+[`size`](size.md) について対数時間。
+
+
+## 備考
+- (2), (4) : この関数がオーバーロード解決に参加する条件は、[`find()`](find.md)メンバ関数の備考欄を参照。
+
+
+## 例
+```cpp example
+#include <iostream>
+#include <string>
+#include <flat_map>
+
+int main()
+{
+  std::flat_map<std::string, int> fm = {
+    {"A", 3},
+    {"B", 1},
+    {"C", 4},
+    {"D", 5}
+  };
+
+  using iterator = decltype(fm)::iterator;
+  std::pair<iterator, iterator> ret = fm.equal_range("B");
+
+  for (iterator it = ret.first; it != ret.second; ++it) {
+    std::cout << it->first << "," << it->second << std::endl;
+  }
+}
+```
+* equal_range[color ff0000]
+
+### 出力
+```
+B,1
+```
+
+
+## 関連項目
+
+| 名前 | 説明 |
+|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
+| [`flat_map::count`](count.md) | 指定したキーにマッチする要素の数を返す |
+| [`flat_map::lower_bound`](lower_bound.md) | 与えられた値より小さくない最初の要素へのイテレータを返す |
+| [`flat_map::upper_bound`](upper_bound.md) | 特定の値よりも大きい最初の要素へのイテレータを返す |
+| [`flat_map::find`](find.md) | 指定したキーで要素を探す |
+

reference/flat_map/flat_map/lower_bound.md

@@ -0,0 +1,119 @@
+# lower_bound
+* flat_map[meta header]
+* std[meta namespace]
+* flat_map[meta class]
+* function[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+iterator lower_bound(const key_type& x);             // (1) C++23
+
+template <class K>
+iterator lower_bound(const K& x);                    // (2) C++23
+
+const_iterator lower_bound(const key_type& x) const; // (3) C++23
+
+template <class K>
+const_iterator lower_bound(const K& x) const;        // (4) C++23
+```
+
+## 概要
+`x` を右辺とする `<` 演算が成り立たない最初の要素を指すイテレータを返す（コンテナの比較オブジェクトが使われる）。すなわちこれは `>=` 演算にあたる。
+
+[`upper_bound()`](upper_bound.md) とは異なり、このメンバ関数は `x` より大きいだけでなく、`x` と等しい場合であってもその要素へのイテレータを返す。
+
+内部的には `map` コンテナ内の全ての要素は常に比較オブジェクトが定義する基準に沿って並んでいるため、この関数が返すいずれかの後に続く全ての要素が `x` より大きいか等しいことに注意。
+
+- (1) : `key_type`型のキーを受け取り、そのキーより小さくない最初の要素へのイテレータを取得する。
+- (2) : `key_type`と比較可能な`K`型のキーを受け取り、そのキーより小さくない最初の要素へのイテレータを取得する。
+- (3) : `const`な`*this`オブジェクトにおいて、`key_type`型のキーを受け取り、そのキーより小さくない最初の要素へのイテレータを取得する。
+- (4) : `const`な`*this`オブジェクトにおいて、`key_type`と比較可能な`K`型のキーを受け取り、そのキーより小さくない最初の要素へのイテレータを取得する。
+
+
+## 戻り値
+- (1), (3) : コンテナ内で `x` を右辺とする `<` 演算が成り立たない最初の要素へのイテレータを返す。そのような要素がない場合は、[`end()`](end.md)を返す。
+- (2), (4) : `key_compare`型の関数オブジェクトを`c`、コンテナ内の各要素が持つキーを`k`として、キーが小さくないか判定する式`!c(k, x)`が`true`となる要素へのイテレータを返す。そのような要素がない場合は、[`end()`](end.md) を返す。
+
+
+## 計算量
+[`size()`](size.md) について対数時間。
+
+
+## 備考
+- (2), (4) : この関数がオーバーロード解決に参加する条件は、[`find()`](find.md)メンバ関数の備考欄を参照。
+
+
+## 例
+```cpp example
+#include <iostream>
+#include <string>
+#include <flat_map>
+
+int main()
+{
+  // (1)
+  {
+    std::flat_map<std::string, int> fm = {
+      {"A", 3},
+      {"B", 1},
+      {"C", 4},
+      {"D", 5}
+    };
+
+    // B以上D以下の範囲を取得
+    decltype(fm)::iterator it = fm.lower_bound("B");
+    decltype(fm)::iterator last = fm.upper_bound("D");
+
+    while (it != last) {
+      std::cout << it->first << ',' << it->second << std::endl;
+      ++it;
+    }
+    std::cout << std::endl;
+  }
+
+  // (2)
+  {
+    std::flat_map<std::string, int, std::less<>> fm = {
+      {"A", 3},
+      {"B", 1},
+      {"C", 4},
+      {"D", 5}
+    };
+
+    // std::lessのvoidに対する特殊化を使用することで、
+    // 文字列リテラルをlower_bound()関数の引数として渡した際に、
+    // std::string型の一時オブジェクトが生成されない。
+    decltype(fm)::iterator it = fm.lower_bound("B");
+    decltype(fm)::iterator last = fm.upper_bound("D");
+
+    while (it != last) {
+      std::cout << it->first << "," << it->second << std::endl;
+      ++it;
+    }
+  }
+}
+```
+* lower_bound[color ff0000]
+* fm.upper_bound[link upper_bound.md]
+* std::less[link /reference/functional/less.md]
+
+### 出力
+```
+B,1
+C,4
+D,5
+
+B,1
+C,4
+D,5
+```
+
+## 関連項目
+
+| 名前 | 説明 |
+|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
+| [`upper_bound`](upper_bound.md) | 特定の値よりも大きい最初の要素へのイテレータを返す |
+| [`equal_range`](equal_range.md) | 指定したキーにマッチする要素範囲を返す |
+| [`find`](find.md) | 指定したキーで要素を探す |
+| [`count`](count.md) | 指定したキーにマッチする要素の数を返す |
+

reference/flat_map/flat_map/upper_bound.md

@@ -0,0 +1,119 @@
+# upper_bound
+* flat_map[meta header]
+* std[meta namespace]
+* flat_map[meta class]
+* function[meta id-type]
+* cpp23[meta cpp]
+
+```cpp
+iterator upper_bound(const key_type& x);             // (1) C++23
+
+template <class K>
+iterator upper_bound(const K& x);                    // (2) C++23
+
+const_iterator upper_bound(const key_type& x) const; // (3) C++23
+
+template <class K>
+const_iterator upper_bound(const K& x) const;        // (4) C++23
+```
+
+## 概要
+`x` より大きいキーを持つコンテナ内の最初の要素を指すイテレータを返す（コンテナの比較オブジェクトを使う）。
+
+[`lower_bound()`](lower_bound.md) と異なり、このメンバ関数は `x` と等しいときは要素へのイテレータを返さず、それは大きい場合にのみ要素へのイテレータを返す。
+
+内部的に、`map` コンテナ内の全ての要素は常に比較オブジェクトで定義された基準に従って並ぶため、この関数が返す値に続く全ての要素は `x` より大きいことに注意。
+
+- (1) : `key_type`型のキーを受け取り、そのキーより大きい最初の要素へのイテレータを取得する。
+- (2) : `key_type`と比較可能な`K`型のキーを受け取り、そのキーより大きい最初の要素へのイテレータを取得する。
+- (3) : `const`な`*this`オブジェクトにおいて、`key_type`型のキーを受け取り、そのキーより大きい最初の要素へのイテレータを取得する。
+- (4) : `const`な`*this`オブジェクトにおいて、`key_type`と比較可能な`K`型のキーを受け取り、そのキーより大きい最初の要素へのイテレータを取得する。
+
+
+## 戻り値
+- (1), (3) : キー`x`より大きい最初の要素へのイテレータを返す。そのような要素がない場合は、[`end()`](end.md)を返す。
+- (2), (4) : `key_compare`型の関数オブジェクトを`c`、コンテナ内の各要素が持つキーを`k`として、キーが小さくないか判定する式`c(x, k)`が`true`となる要素へのイテレータを返す。そのような要素がない場合は、[`end()`](end.md) を返す。
+
+
+## 計算量
+[`size()`](size.md) について対数時間。
+
+
+## 備考
+- (2), (4) : この関数がオーバーロード解決に参加する条件は、[`find()`](find.md)メンバ関数の備考欄を参照。
+
+
+## 例
+```cpp example
+#include <iostream>
+#include <string>
+#include <flat_map>
+
+int main()
+{
+  // (1)
+  {
+    std::flat_map<std::string, int> fm = {
+      {"A", 3},
+      {"B", 1},
+      {"C", 4},
+      {"D", 5}
+    };
+
+    // B以上D以下の範囲を取得
+    decltype(fm)::iterator it = fm.lower_bound("B");
+    decltype(fm)::iterator last = fm.upper_bound("D");
+
+    while (it != last) {
+      std::cout << it->first << ',' << it->second << std::endl;
+      ++it;
+    }
+    std::cout << std::endl;
+  }
+
+  // (2)
+  {
+    std::flat_map<std::string, int, std::less<>> fm = {
+      {"A", 3},
+      {"B", 1},
+      {"C", 4},
+      {"D", 5}
+    };
+
+    // std::lessのvoidに対する特殊化を使用することで、
+    // 文字列リテラルをlower_bound()関数の引数として渡した際に、
+    // std::string型の一時オブジェクトが生成されない。
+    decltype(fm)::iterator it = fm.lower_bound("B");
+    decltype(fm)::iterator last = fm.upper_bound("D");
+
+    while (it != last) {
+      std::cout << it->first << "," << it->second << std::endl;
+      ++it;
+    }
+  }
+}
+```
+* upper_bound[color ff0000]
+* fm.lower_bound[link lower_bound.md]
+* std::less[link /reference/functional/less.md]
+
+### 出力
+```
+B,1
+C,4
+D,5
+
+B,1
+C,4
+D,5
+```
+
+## 関連項目
+
+| 名前 | 説明 |
+|-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| [`lower_bound`](lower_bound.md) | 与えられた値よりも小さくない最初の要素へのイテレータを返す |
+| [`equal_range`](equal_range.md) | 指定したキーにマッチする要素範囲を返す |
+| [`find`](find.md) | 指定したキーで要素を探す |
+| [`count`](count.md) | 指定したキーにマッチする要素の数を返す |
+

reference/map/map/equal_range.md

@@ -22,7 +22,7 @@ pair<const_iterator, const_iterator>
 ## 概要
 コンテナ内の、`x` と等しいキー要素を全て含む範囲の境界を返す。`map` コンテナではキーの重複は無いため、この範囲は最大一つの要素を含む。 
 
-もし `x` がコンテナ内のどのキーともマッチしなかった場合、戻り値の範囲は長さ 0 になり、両方のイテレータは `x` より大きく最も近い値を指す。そうでない場合、`x` がコンテナ内の全ての要素よりも大きい場合は [`end`](/end.md) を指す。
+もし `x` がコンテナ内のどのキーともマッチしなかった場合、戻り値の範囲は長さ 0 になり、両方のイテレータは `x` より大きく最も近い値を指す。そうでない場合、`x` がコンテナ内の全ての要素よりも大きい場合は [`end`](end.md) を指す。
 
 - (1) : `key_type`型のキーを受け取り、そのキーと等価なキー要素を全て含むイテレータ範囲を取得する。
 - (2) : `key_type`と比較可能な`K`型のキーを受け取り、そのキーと等価なキー要素を全て含むイテレータ範囲を取得する。