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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::map::emplace_hint -	std::map::emplace_hint

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

	  Inserts a new	element	into the container as close as possible	to the
       position	just
	  before hint.

	  The  constructor  of	the  element  type   (value_type,   that   is,
       std::pair<const Key, T>)
	  is  called  with exactly the same arguments as supplied to the func-
       tion, forwarded
	  with std::forward<Args>(args)....

	  No iterators or references are invalidated.

Parameters
	  hint - iterator to the position before which the new element will be
       inserted
	  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
	  Logarithmic in the size of the container in general,	but  amortized
       constant	if the
	  new element is inserted just before hint.

Example
       // Run this code

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

	const int n_operations = 100'500'0;

	std::size_t map_emplace()
	{
	    std::map<int, char>	map;
	    for	(int i = 0; i <	n_operations; ++i)
		map.emplace(i, 'a');
	    return map.size();
	}

	std::size_t map_emplace_hint()
	{
	    std::map<int, char>	map;
	    auto it = map.begin();
	    for	(int i = 0; i <	n_operations; ++i)
	    {
		map.emplace_hint(it, i,	'b');
		it = map.end();
	    }
	    return map.size();
	}

	std::size_t map_emplace_hint_wrong()
	{
	    std::map<int, char>	map;
	    auto it = map.begin();
	    for	(int i = n_operations; i > 0; --i)
	    {
		map.emplace_hint(it, i,	'c');
		it = map.end();
	    }
	    return map.size();
	}

	std::size_t map_emplace_hint_corrected()
	{
	    std::map<int, char>	map;
	    auto it = map.begin();
	    for	(int i = n_operations; i > 0; --i)
	    {
		map.emplace_hint(it, i,	'd');
		it = map.begin();
	    }
	    return map.size();
	}

	std::size_t map_emplace_hint_closest()
	{
	    std::map<int, char>	map;
	    auto it = map.begin();
	    for	(int i = 0; i <	n_operations; ++i)
		it = map.emplace_hint(it, i, 'e');
	    return map.size();
	}

	double time_it(std::function<std::size_t()> map_test,
		       std::string what	= "", double ratio = 0.0)
	{
	    const auto start = std::chrono::system_clock::now();
	    const std::size_t map_size = map_test();
	    const auto stop = std::chrono::system_clock::now();
	    std::chrono::duration<double, std::milli> time = stop - start;
	    if (what.size() && map_size)
		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(map_emplace); // cache warmup
	    const auto x = time_it(map_emplace,	"plain emplace");
	    time_it(map_emplace_hint, "emplace with correct hint", x);
	    time_it(map_emplace_hint_wrong, "emplace with wrong	hint", x);
	    time_it(map_emplace_hint_corrected,	"corrected emplace", x);
	    time_it(map_emplace_hint_closest, "emplace using  returned	itera-
       tor", x);
	}

Possible output:
	365.08ms for plain emplace (ratio: 1.00)
	 96.54ms for emplace with correct hint (ratio: 3.78)
	409.40ms for emplace with wrong	hint (ratio: 0.89)
	 85.57ms for corrected emplace (ratio: 4.27)
	 84.31ms for emplace using returned iterator (ratio: 4.33)

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

http://cppreference.com		  2024.06.10	     std::map::emplace_hint(3)

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

home | help