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.

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		    Value	   Std
       Feature
							       Heterogeneous
       comparison lookup
	  __cpp_lib_generic_associative_lookup	201304L	(C++14)	in associative
       containers, for
							       overloads (3,4)

Example
       // Run this code

	#include <iostream>
	#include <map>

	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		  2024.06.10	      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.1.quarterly>

home | help