Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::map::equal_range(3)      C++ Standard Libary     std::map::equal_range(3)

NAME
       std::map::equal_range - std::map::equal_range

Synopsis
	  std::pair<iterator,iterator>	 equal_range(	const	Key&   key  );
       (1)
	  std::pair<const_iterator,const_iterator>  equal_range(  const	  Key&
       (2)
	  key )	const;
	  template<		     class		   K		     >
       (3) (since C++14)
	  std::pair<iterator,iterator> equal_range( const K& x );
	  template< class K >
	  std::pair<const_iterator,const_iterator> equal_range(	const K&  x  )
       (4) (since C++14)
	  const;

	  Returns  a  range  containing	all elements with the given key	in the
       container. The
	  range	is defined by two iterators, one pointing to the first element
       that is not
	  less than key	and another pointing to	the first element greater than
       key.
	  Alternatively,   the	 first	 iterator   may	  be   obtained	  with
       lower_bound(), and the second
	  with upper_bound().

	  1,2) Compares	the keys to key.
	  3,4) Compares	the keys to the	value x. This overload participates in
       overload
	  resolution only if the qualified-id Compare::is_transparent is valid
       and denotes a
	  type.	 It  allows  calling this function without constructing	an in-
       stance of Key.

	   This	section	is incomplete
	   Reason: explain better

Parameters
	  key -	key value to compare the elements to
	  x   -	alternative value that can be compared to Key

Return value
	  std::pair containing a pair of iterators defining the	wanted	range:
       the first
	  pointing to the first	element	that is	not less than key and the sec-
       ond pointing to
	  the first element greater than key.

	  If there are no elements not less than key, past-the-end (see	end())
       iterator	is
	  returned  as	the  first element. Similarly if there are no elements
       greater than key,
	  past-the-end iterator	is returned as the second element.

Complexity
	  Logarithmic in the size of the container.

Notes
	  Feature-test macro: __cpp_lib_generic_associative_lookup (for	 over-
       loads (3,4))

Example
       // Run this code

	#include <map>
	#include <iostream>

	int main()
	{
	    const std::map<int,	const char*> m{
		{ 0, "zero" },
		{ 1, "one" },
		{ 2, "two" },
	    };

	    {
		auto p = m.equal_range(1);
		for (auto& q = p.first;	q != p.second; ++q) {
		    std::cout  <<  "m["	 << q->first <<	"] = " << q->second <<
       '\n';
		}

		if (p.second ==	m.find(2)) {
		    std::cout << "end of equal_range  (p.second)  is  one-past
       p.first\n";
		} else {
		    std::cout << "unexpected; p.second expected	to be one-past
       p.first\n";
		}
	    }

	    {
		auto pp	= m.equal_range(-1);
		if (pp.first ==	m.begin()) {
		    std::cout  << "pp.first is iterator	to first not-less than
       -1\n";
		} else {
		    std::cout << "unexpected pp.first\n";
		}

		if (pp.second == m.begin()) {
		    std::cout <<  "pp.second  is  iterator  to	first  element
       greater-than -1\n";
		} else {
		    std::cout << "unexpected pp.second\n";
		}
	    }

	    {
		auto ppp = m.equal_range(3);
		if (ppp.first == m.end()) {
		    std::cout << "ppp.first is iterator	to first not-less than
       3\n";
		} else {
		    std::cout << "unexpected ppp.first\n";
		}

		if (ppp.second == m.end()) {
		    std::cout  <<  "ppp.second	is  iterator  to first element
       greater-than 3\n";
		} else {
		    std::cout << "unexpected ppp.second\n";
		}
	    }
	}

Output:
	m[1] = one
	end of equal_range (p.second) is one-past p.first
	pp.first is iterator to	first not-less than -1
	pp.second is iterator to first element greater-than -1
	ppp.first is iterator to first not-less	than 3
	ppp.second is iterator to first	element	greater-than 3

See also
	  find	      finds element with specific key
		      (public member function)
	  contains    checks if	the container contains element	with  specific
       key
	  (C++20)     (public member function)
	  count	      returns the number of elements matching specific key
		      (public member function)
	  upper_bound  returns	an  iterator to	the first element greater than
       the given key
		      (public member function)
	  lower_bound returns an iterator to the first element not  less  than
       the given key
		      (public member function)
	  equal_range returns range of elements	matching a specific key
		      (function	template)

http://cppreference.com		  2022.07.31	      std::map::equal_range(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::map::equal_range&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help