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	to the container as close as possible  to  the
       position	just
	  before  hint.	 The  element is constructed in-place, i.e. no copy or
       move operations
	  are performed.

	  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
	  Returns an iterator to the newly inserted element.

	  If the insertion failed because the element already exists,  returns
       an iterator to
	  the already existing element with the	equivalent key.

Exceptions
	  If an	exception is thrown by any operation, this function has	no ef-
       fect (strong
	  exception 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 <functional>
	#include <iomanip>
	#include <iostream>
	#include <map>

	const int n_operations = 100500;

	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();
	}

	void timeit(std::function<std::size_t()> map_test, std::string what  =
       "") {
	    auto start = std::chrono::system_clock::now();
	    std::size_t	mapsize	= map_test();
	    auto stop =	std::chrono::system_clock::now();
	    std::chrono::duration<double, std::milli> time = stop - start;
	    if (what.size() > 0	&& mapsize > 0)	{
		std::cout  <<  std::setw(5)  <<	time.count() <<	"  ms for " <<
       what << '\n';
	    }
	}

	int main() {
	    std::cout << std::fixed << std::setprecision(2);
	    timeit(map_emplace); // stack warmup
	    timeit(map_emplace,	"plain emplace");
	    timeit(map_emplace_hint, "emplace with correct hint");
	    timeit(map_emplace_hint_wrong, "emplace with wrong hint");
	    timeit(map_emplace_hint_corrected, "corrected emplace");
	    timeit(map_emplace_hint_closest, "emplace  using  returned	itera-
       tor");
	}

Possible output:
	22.64  ms for plain emplace
	 8.81  ms for emplace with correct hint
	22.27  ms for emplace with wrong hint
	 7.76  ms for corrected	emplace
	 8.30  ms for emplace using returned iterator

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		  2022.07.31	     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.0>

home | help