最終更新日時: 2026年02月17日 23時22分33秒 (JST)
Akira Takahashi が更新

履歴 編集

function
<unordered_set>

# std::unordered_multiset::equal_range(C++11)

    pair<iterator, iterator>
      equal_range(const key_type& x); // (1) C++11
    constexpr pair<iterator, iterator>
      equal_range(const key_type& x); // (1) C++26

    pair<const_iterator, const_iterator>
      equal_range(const key_type& x) const; // (2) C++11
    constexpr pair<const_iterator, const_iterator>
      equal_range(const key_type& x) const; // (2) C++26

    template <class K>
    pair<iterator, iterator>
      equal_range(const K& k); // (3) C++20
    template <class K>
    constexpr pair<iterator, iterator>
      equal_range(const K& k); // (3) C++26

    template <class K>
    pair<const_iterator, const_iterator>
      equal_range(const K& k) const; // (4) C++20
    template <class K>
    constexpr pair<const_iterator, const_iterator>
      equal_range(const K& k) const; // (4) C++26

## 概要

コンテナ内の、指定されたキーと等しい全てのキー要素を含む範囲の境界を返す。

もし指定されたキーがコンテナ内のどのキーともマッチしなかった場合、戻り値の範囲は長さ 0 になり、両方のイテレータは `end` を指す。

- (1) : 非`const`な`this`に対してキー`x`を検索し、合致する全ての要素を含む範囲を取得する
- (2) : `const`な`this`に対してキー`x`を検索し、合致する全ての要素を含む範囲を取得する
- (3) : 非`const`な`this`に対してキー`k`を透過的に検索し、合致する全ての要素を含む範囲を取得する
- (4) : `const`な`this`に対してキー`k`を透過的に検索し、合致する全ての要素を含む範囲を取得する

(3), (4)の透過的な検索は、`Pred::is_transparent`および`Hash::is_transparent`が定義される場合に有効になる機能であり、例として`unordered_multiset<string> s;`に対して`s.equal_range("key");`のように`string`型のキーを持つ連想コンテナの検索インタフェースに文字列リテラルを渡した際、`string`の一時オブジェクトが作られないようにできる。詳細は`std::hash`クラスのページを参照。

## テンプレートパラメータ制約

- (3), (4) : `Pred::is_transparent`型および`Hash::is_transparent`型が定義されていること

## 戻り値

合致する要素の範囲を表す `pair` オブジェクトを返す。`pair::first` は 範囲の下境界にあたり、`pair::second` は 範囲の上境界にあたる。

そのような要素がない場合には、`make_pair(end(), end())`を返す。

`iterator` はメンバ型であり `unordered_multiset` において双方向イテレータとして定義される。

## 計算量

- 平均： 定数時間
- 最悪： `size` について線形時間

## 例

    #include <iostream>
    #include <string>
    #include <unordered_set>
    #include <algorithm>
    #include <iterator>

    template <class Iter>
    void print_range(const std::string& label, Iter begin, Iter it1, Iter it2, std::ostream& os = std::cout)
    {
      os << label << ": " << "[" << std::distance(begin, it1) << ", "  << std::distance(begin, it2) << ")" << std::endl;
    }

    int main()
    {
      std::unordered_multiset<int> ums{ 1, 3, 5, 7, 9, 1, 3, 5, 7, 9, };

      std::copy(ums.begin(), ums.end(), std::ostream_iterator<int>(std::cout, ", "));
      std::cout << std::endl;

      auto p1 = ums.equal_range(5);
      print_range("equal_range(5)", ums.begin(), p1.first, p1.second);

      auto p2 = ums.equal_range(8);
      print_range("equal_range(8)", ums.begin(), p2.first, p2.second);
    }

### 出力例

    9, 9, 7, 7, 5, 5, 1, 1, 3, 3,
    equal_range(5): [4, 6)
    equal_range(8): [10, 10)

## バージョン

### 言語

- C++11

### 処理系

- Clang: 3.0 ✅, 3.1 ✅
- GCC: 4.4.7 ✅, 4.5.3 ✅, 4.6.3 ✅, 4.7.0 ✅
- ICC: ?
- Visual C++: ?

## 関連項目

名前 | 説明
--- | ---
`count` | 指定したキーにマッチする要素の数を返す
`find` | 指定したキーで要素を探す

## 参照

- P0919R3 Heterogeneous lookup for unordered containers
- P3372R3 constexpr containers and adaptors