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

FreeBSD Manual Pages

  
 
  

home | help 
std::unorde...mplace_hint(3)  C++ Standard Libary std::unorde...mplace_hint(3)

NAME
       std::unordered_set::emplace_hint	- std::unordered_set::emplace_hint

Synopsis
	  template<		   class...		  Args		     >
       (since C++11)
	  iterator emplace_hint( const_iterator	hint, Args&&...	args );

	  Inserts a new	element	into the container, using hint as a suggestion
       where the
	  element should go.

	  The constructors of the key and mapped value are called with exactly
       the same
	  arguments as supplied	to  the	 function,  forwarded  with  std::for-
       ward<Args>(args)....

	  If  after  the  operation the	new number of elements is greater than
       old
	  max_load_factor() * bucket_count() a rehashing takes place.
	  If rehashing occurs (due to the insertion), all iterators are	inval-
       idated. Otherwise
	  (no rehashing), iterators are	not invalidated.

Parameters
	  hint - iterator, used	as a suggestion	as to where to insert the  new
       element
	  args - arguments to forward to the constructor of the	element

Return value
	  An  iterator	to  the	 inserted element, or to the element that pre-
       vented the insertion.

Exceptions
	  If an	exception is thrown for	any reason, this function has  no  ef-
       fect (strong
	  exception safety guarantee).

Complexity
	  Amortized  constant on average, worst	case linear in the size	of the
       container.

Example
       // Run this code

	#include <chrono>
	#include <cstddef>
	#include <functional>
	#include <iomanip>
	#include <iostream>
	#include <unordered_set>

	const int n_operations = 100'500'0;

	std::size_t set_emplace()
	{
	    std::unordered_set<int> set;
	    for	(int i = 0; i <	n_operations; ++i)
		set.emplace(i);
	    return set.size();
	}

	std::size_t set_emplace_hint()
	{
	    std::unordered_set<int> set;
	    auto it = set.begin();
	    for	(int i = 0; i <	n_operations; ++i)
	    {
		set.emplace_hint(it, i);
		it = set.end();
	    }
	    return set.size();
	}

	std::size_t set_emplace_hint_wrong()
	{
	    std::unordered_set<int> set;
	    auto it = set.begin();
	    for	(int i = n_operations; i > 0; --i)
	    {
		set.emplace_hint(it, i);
		it = set.end();
	    }
	    return set.size();
	}

	std::size_t set_emplace_hint_corrected()
	{
	    std::unordered_set<int> set;
	    auto it = set.begin();
	    for	(int i = n_operations; i > 0; --i)
	    {
		set.emplace_hint(it, i);
		it = set.begin();
	    }
	    return set.size();
	}

	std::size_t set_emplace_hint_closest()
	{
	    std::unordered_set<int> set;
	    auto it = set.begin();
	    for	(int i = 0; i <	n_operations; ++i)
		it = set.emplace_hint(it, i);
	    return set.size();
	}

	double time_it(std::function<std::size_t()> set_test,
		       const char* what	= nullptr,
		       double ratio = 0.0)
	{
	    const auto start = std::chrono::system_clock::now();
	    const std::size_t setsize =	set_test();
	    const auto stop = std::chrono::system_clock::now();
	    const std::chrono::duration<double,	 std::milli>  time  =  stop  -
       start;
	    if (what !=	nullptr	&& setsize > 0)
		std::cout << std::setw(8) << time << " for " <<	what <<	" (ra-
       tio: "
			  <<  (ratio  ==  0.0 ?	1.0 : ratio / time.count()) <<
       ")\n";
	    return time.count();
	}

	int main()
	{
	    std::cout << std::fixed << std::setprecision(2);
	    time_it(set_emplace); // cache warmup
	    const auto x = time_it(set_emplace,	"plain emplace");
	    time_it(set_emplace_hint, "emplace with correct hint", x);
	    time_it(set_emplace_hint_wrong, "emplace with wrong	hint", x);
	    time_it(set_emplace_hint_corrected,	"corrected emplace", x);
	    time_it(set_emplace_hint_closest, "emplace using  returned	itera-
       tor", x);
	}

Possible output:
	146.88ms for plain emplace (ratio: 1.00)
	168.20ms for emplace with correct hint (ratio: 0.87)
	168.78ms for emplace with wrong	hint (ratio: 0.87)
	166.58ms for corrected emplace (ratio: 0.88)
	168.27ms for emplace using returned iterator (ratio: 0.87)

See also
	  emplace constructs element in-place
		  (public member function)
		  inserts elements
	  insert  or nodes
		  (since C++17)
		  (public member function)

http://cppreference.com		  2024.06.10	  std::unorde...mplace_hint(3)

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

home | help