GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing cplusplus.com — std::map::equal_range

Reference

C library:
- <cassert> (assert.h)
- <cctype> (ctype.h)
- <cerrno> (errno.h)
- C++11
  <cfenv> (fenv.h)
- <cfloat> (float.h)
- C++11
  <cinttypes> (inttypes.h)
- <ciso646> (iso646.h)
- <climits> (limits.h)
- <clocale> (locale.h)
- <cmath> (math.h)
- <csetjmp> (setjmp.h)
- <csignal> (signal.h)
- <cstdarg> (stdarg.h)
- C++11
  <cstdbool> (stdbool.h)
- <cstddef> (stddef.h)
- C++11
  <cstdint> (stdint.h)
- <cstdio> (stdio.h)
- <cstdlib> (stdlib.h)
- <cstring> (string.h)
- C++11
  <ctgmath> (tgmath.h)
- <ctime> (time.h)
- C++11
  <cuchar> (uchar.h)
- <cwchar> (wchar.h)
- <cwctype> (wctype.h)
Containers:
- C++11
  <array>
- <deque>
- C++11
  <forward_list>
- <list>
- <map>
- <queue>
- <set>
- <stack>
- C++11
  <unordered_map>
- C++11
  <unordered_set>
- <vector>
Input/Output:
- <fstream>
- <iomanip>
- <ios>
- <iosfwd>
- <iostream>
- <istream>
- <ostream>
- <sstream>
- <streambuf>
Multi-threading:
- C++11
  <atomic>
- C++11
  <condition_variable>
- C++11
  <future>
- C++11
  <mutex>
- C++11
  <thread>
Other:
- <algorithm>
- <bitset>
- C++11
  <chrono>
- C++11
  <codecvt>
- <complex>
- <exception>
- <functional>
- C++11
  <initializer_list>
- <iterator>
- <limits>
- <locale>
- <memory>
- <new>
- <numeric>
- C++11
  <random>
- C++11
  <ratio>
- C++11
  <regex>
- <stdexcept>
- <string>
- C++11
  <system_error>
- C++11
  <tuple>
- C++11
  <type_traits>
- C++11
  <typeindex>
- <typeinfo>
- <utility>
- <valarray>

map

map::~map
map::map
member functions
- C++11
  map::at
- map::begin
- C++11
  map::cbegin
- C++11
  map::cend
- map::clear
- map::count
- C++11
  map::crbegin
- C++11
  map::crend
- C++11
  map::emplace
- C++11
  map::emplace_hint
- map::empty
- map::end
- map::equal_range
- map::erase
- map::find
- map::get_allocator
- map::insert
- map::key_comp
- map::lower_bound
- map::max_size
- map::operator[]
- map::operator=
- map::rbegin
- map::rend
- map::size
- map::swap
- map::upper_bound
- map::value_comp
non-member overloads
- relational operators (map)
- swap (map)

Reference
<map>
map
equal_range

public member function

<map>

std::map::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.

Because the elements in a map container have unique keys, the range returned will contain a single element at most.

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 map 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 map 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 map containers is itself also a pair type: pair<const key_type, mapped_type>.

Example

// map::equal_range
#include <iostream>
#include <map>

int main ()
{
  std::map<char,int> mymap;

  mymap['a']=10;
  mymap['b']=20;
  mymap['c']=30;

  std::pair<std::map<char,int>::iterator,std::map<char,int>::iterator> ret;
  ret = mymap.equal_range('b');

  std::cout << "lower bound points to: ";
  std::cout << ret.first->first << " => " << ret.first->second << '\n';

  std::cout << "upper bound points to: ";
  std::cout << ret.second->first << " => " << ret.second->second << '\n';

  return 0;
}

lower bound points to: 'b' => 20
upper bound points to: 'c' => 30

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.

member functions

non-member overloads