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

FreeBSD Manual Pages

  
 
  

home | help 
std::unorde...map::emplace(3) C++ Standard Libarystd::unorde...map::emplace(3)

NAME
       std::unordered_map::emplace - std::unordered_map::emplace

Synopsis
	  template< class... Args >				(since C++11)
	  std::pair<iterator, bool> emplace( Args&&... args );

	  Inserts  a  new element into the container constructed in-place with
       the given args,
	  if there is no element with the key in the container.

	  The constructor of the new element (i.e. std::pair<const Key,	T>) is
       called with
	  exactly the same arguments as	supplied to emplace, forwarded via
	  std::forward<Args>(args).... The element may be constructed even  if
       there already is
	  an  element  with  the key in	the container, in which	case the newly
       constructed
	  element will be destroyed immediately.

	  Careful use of emplace allows	the  new  element  to  be  constructed
       while avoiding
	  unnecessary copy or move operations.

	  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
	  args - arguments to forward to the constructor of the	element

Return value
	  A pair consisting of an iterator to the inserted element (or to  the
       element that
	  prevented the	insertion) and a bool value set	to true	if and only if
       the insertion
	  took place.

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 <iostream>
	#include <string>
	#include <utility>
	#include <unordered_map>

	int main()
	{
	    std::unordered_map<std::string, std::string> m;

	    // uses pair's move	constructor
	    m.emplace(std::make_pair(std::string("a"), std::string("a")));

	    // uses pair's converting move constructor
	    m.emplace(std::make_pair("b", "abcd"));

	    // uses pair's template constructor
	    m.emplace("d", "ddd");

	    // emplace with duplicate key has no effect
	    m.emplace("d", "DDD");

	    // uses pair's piecewise constructor
	    m.emplace(std::piecewise_construct,
		      std::forward_as_tuple("c"),
		      std::forward_as_tuple(10,	'c'));
	    // an alternative is: m.try_emplace("c", 10, 'c');

	    for	(const auto& p : m)
		std::cout << p.first <<	" => " << p.second << '\n';
	}

Possible output:
	a => a
	b => abcd
	c => cccccccccc
	d => ddd

See also
	  emplace_hint constructs elements in-place using a hint
		       (public member function)
	  try_emplace	inserts	in-place if the	key does not exist, does noth-
       ing if the key
	  (C++17)      exists
		       (public member function)
		       inserts elements
	  insert       or nodes
		       (since C++17)
		       (public member function)

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

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

home | help