public member function
<map>

std::multimap::equal_range

pair<const_iterator,const_iterator> equal_range (const key_type& k) const;
pair<iterator,iterator>             equal_range (const key_type& k);
Get range of equal elements
Returns the bounds of a range that includes all the elements in the container which have a key equivalent to k.

If no matches are found, the range returned has a length of zero, with both iterators pointing to the first element that has a key considered to go after k according to the container's internal comparison object (key_comp).

Two keys are considered equivalent if the container's comparison object returns false reflexively (i.e., no matter the order in which the keys are passed as arguments).

Parameters

k
Key to search for.
Member type key_type is the type of the elements in the container, defined in multimap as an alias of its first template parameter (Key).

Return value

The function returns a pair, whose member pair::first is the lower bound of the range (the same as lower_bound), and pair::second is the upper bound (the same as upper_bound).

If the multimap object is const-qualified, the function returns a pair of const_iterator. Otherwise, it returns a pair of iterator.

Member types iterator and const_iterator are bidirectional iterator types pointing to elements (of type value_type).
Notice that value_type in multimap containers is itself also a pair type: pair<const key_type, mapped_type>.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
// multimap::equal_range
#include <iostream>
#include <map>

int main ()
{
  std::multimap<char,int> mymm;

  mymm.insert(std::pair<char,int>('a',10));
  mymm.insert(std::pair<char,int>('b',20));
  mymm.insert(std::pair<char,int>('b',30));
  mymm.insert(std::pair<char,int>('b',40));
  mymm.insert(std::pair<char,int>('c',50));
  mymm.insert(std::pair<char,int>('c',60));
  mymm.insert(std::pair<char,int>('d',60));

  std::cout << "mymm contains:\n";
  for (char ch='a'; ch<='d'; ch++)
  {
    std::pair <std::multimap<char,int>::iterator, std::multimap<char,int>::iterator> ret;
    ret = mymm.equal_range(ch);
    std::cout << ch << " =>";
    for (std::multimap<char,int>::iterator it=ret.first; it!=ret.second; ++it)
      std::cout << ' ' << it->second;
    std::cout << '\n';
  }

  return 0;
}


mymm contains:
a => 10
b => 20 30 40
c => 50 60
d => 60

Complexity

Logarithmic in size.

Iterator validity

No changes.

Data races

The container is accessed (neither the const nor the non-const versions modify the container).
No mapped values are accessed: concurrently accessing or modifying elements is safe.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the container.

See also

multimap::count
Count elements with a specific key (public member function )
multimap::lower_bound
Return iterator to lower bound (public member function )
multimap::upper_bound
Return iterator to upper bound (public member function )
multimap::find
Get iterator to element (public member function )

C++