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

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

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

	If  a key equivalent to k already exists in the container, does nothing.
     Otherwise,
	inserts a new element into the container  with	key  k	and  value  con-
     structed with args.
	In such case:

	1) Behaves like emplace except that the element is constructed as
	value_type(std::piecewise_construct,

		   std::forward_as_tuple(k),

		   std::forward_as_tuple(std::forward<Args>(args)...))
	2) Behaves like emplace except that the element is constructed as
	value_type(std::piecewise_construct,

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

		   std::forward_as_tuple(std::forward<Args>(args)...))
	3) Behaves like emplace except that the element is constructed as
	value_type(std::piecewise_construct,

		   std::forward_as_tuple(std::forward<K>(k)),

		   std::forward_as_tuple(std::forward<Args>(args)...))
	4) Behaves like emplace_hint except that the element is constructed as
	value_type(std::piecewise_construct,

		   std::forward_as_tuple(k),

		   std::forward_as_tuple(std::forward<Args>(args)...))
	5) Behaves like emplace_hint except that the element is constructed as
	value_type(std::piecewise_construct,

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

		   std::forward_as_tuple(std::forward<Args>(args)...))
	6) Behaves like emplace_hint except that the element is constructed as
	value_type(std::piecewise_construct,

		   std::forward_as_tuple(std::forward<K>(k)),

		   std::forward_as_tuple(std::forward<Args>(args)...))
	1-6)  If  value_type is not EmplaceConstructible into unordered_map from
     the
	corresponding expression, the behavior is undefined.
	3) This overload participates in overload resolution only if all follow-
     ing
	conditions are satisfied:
	  *  std::is_convertible_v<K&&,  const_iterator>  and	std::is_convert-
     ible_v<K&&,
	    iterator> are both false.
	  * Hash::is_transparent and KeyEqual::is_transparent are valid and each
     denotes a
	    type.
	If  hash_function()(u.first)  != hash_function()(k) || contains(u.first)
     is true, the
	behavior is undefined, where u is the new element to be inserted.
	6)  This  overload  participates  in   overload   resolution   only   if
     Hash::is_transparent
	and KeyEqual::is_transparent are both valid and each denotes a type.
	If  hash_function()(u.first)  != hash_function()(k) || contains(u.first)
     is true, the
	behavior is undefined, where u is the new element to be inserted.

	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  invali-
     dated. Otherwise
	(no rehashing), iterators are not invalidated.

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

Return value
	1-3) Same as for emplace.
	4-6) Same as for emplace_hint.

Complexity
	1-3) Same as for emplace.
	4-6) Same as for emplace_hint.

Notes
	Unlike	insert or emplace, these functions do not move from rvalue argu-
     ments 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 construct a
     value_type
	(that is, a std::pair).

	Overloads (3,6) can be called without constructing  an	object	of  type
     Key.

		  Feature-test	     macro		       Value	     Std
     Feature   __cpp_lib_unordered_map_try_emplace	       201411L	 (C++17)
     std::unordered_map::try_emplace,
								   std::un-
     ordered_map::insert_or_assign
								   Heterogeneous
     overloads	for  the  __cpp_lib_associative_heterogeneous_insertion  202311L
     (C++26) remaining member functions in
								   ordered   and
     unordered associative
								   containers.
     Overloads (3) and (6).

Example
     // Run this code

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

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

      void 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
		     (public member function)
	emplace_hint constructs elements in-place using a hint
		     (public member function)
		     inserts elements
	insert	     or nodes
		     (since C++17)
		     (public member function)

http://cppreference.com 	   2024.06.10	   std::unorde...:try_emplace(3)
home | help