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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::unordered_map::try_emplace - std::unordered_map::try_emplace

Synopsis
	  template<		   class...		  Args		     >
       (1) (since C++17)
	  pair<iterator, bool> try_emplace( const Key& k, Args&&... args );
	  template<		  class...		 Args		     >
       (2) (since C++17)
	  pair<iterator, bool> try_emplace( Key&& k, Args&&... args );
	  template< class... Args >
	  iterator  try_emplace(  const_iterator hint, const Key& k, Args&&...
       (3) (since C++17)
	  args );
	  template< class... Args >
	  iterator try_emplace(	const_iterator hint, Key&& k,  Args&&...  args
       (4) (since C++17)
	  );

	  Inserts  a  new element into the container with key k	and value con-
       structed	with args,
	  if there is no element with the key in the container.

	  1) If	a key equivalent to k already exists in	 the  container,  does
       nothing.
	  Otherwise,  behaves  like  emplace  except  that the element is con-
       structed	as
	  value_type(std::piecewise_construct,

	  std::forward_as_tuple(k),

	  std::forward_as_tuple(std::forward<Args>(args)...))
	  2) If	a key equivalent to k already exists in	 the  container,  does
       nothing.
	  Otherwise,  behaves  like  emplace  except  that the element is con-
       structed	as
	  value_type(std::piecewise_construct,

	  std::forward_as_tuple(std::move(k)),

	  std::forward_as_tuple(std::forward<Args>(args)...))
	  3) If	a key equivalent to k already exists in	 the  container,  does
       nothing.
	  Otherwise, behaves like emplace_hint except that the element is con-
       structed	as
	  value_type(std::piecewise_construct,

	  std::forward_as_tuple(k),

	  std::forward_as_tuple(std::forward<Args>(args)...))
	  4)  If  a  key equivalent to k already exists	in the container, does
       nothing.
	  Otherwise, behaves like emplace_hint except that the element is con-
       structed	as
	  value_type(std::piecewise_construct,

	  std::forward_as_tuple(std::move(k)),

	  std::forward_as_tuple(std::forward<Args>(args)...))

	  If rehashing occurs due to the insertion, all	iterators are  invali-
       dated. Otherwise
	  iterators  are not affected. References are not invalidated. Rehash-
       ing occurs only if
	  the  new  number  of	elements   is	greater	  than	 max_load_fac-
       tor()*bucket_count().

Parameters
	  k    - the key used both to look up and to insert if not found
	  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
	  1,2) Same as for emplace
	  3,4) Same as for emplace_hint

Complexity
	  1,2) Same as for emplace
	  3,4) Same as for emplace_hint

Notes
	  Unlike  insert  or  emplace, these functions do not move from	rvalue
       arguments if the
	  insertion does not happen, which makes it easy  to  manipulate  maps
       whose values are
	  move-only    types,	 such	 as    std::unordered_map<std::string,
       std::unique_ptr<foo>>. In
	  addition, try_emplace	treats	the  key  and  the  arguments  to  the
       mapped_type
	  separately,  unlike  emplace,	 which	requires the arguments to con-
       struct a	value_type
	  (that	is, a std::pair).

	  Feature-test macro: __cpp_lib_unordered_map_try_emplace

Example
       // Run this code

	#include <iostream>
	#include <utility>
	#include <string>

	#include <unordered_map>

	auto print_node	= [](const auto	&node) {
	    std::cout << "[" <<	node.first << "] = " <<	node.second << '\n';
	};

	auto print_result = [](auto const &pair) {
	    std::cout << (pair.second ?	"inserted: " : "ignored:  ");
	    print_node(*pair.first);
	};

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

	    print_result( m.try_emplace("a", "a"s) );
	    print_result( m.try_emplace("b", "abcd") );
	    print_result( m.try_emplace("c", 10, 'c') );
	    print_result( m.try_emplace("c", "Won't be inserted") );

	    for	(const auto &p : m) { print_node(p); }
	}

Possible output:
	inserted: [a] =	a
	inserted: [b] =	abcd
	inserted: [c] =	cccccccccc
	ignored:  [c] =	cccccccccc
	[a] = a
	[b] = abcd
	[c] = cccccccccc

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

http://cppreference.com		  2022.07.31	 std::unorde...:try_emplace(3)

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

home | help