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

NAME
     std::map::try_emplace - std::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 map from the corre-
     sponding
	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.
	  *  The  qualified-id	Compare::is_transparent  is  valid and denotes a
     type.
	If equal_range(u.first) == equal_range(k) is false, the behavior is  un-
     defined, where
	u is the new element to be inserted.
	6)  This overload participates in overload resolution only if the quali-
     fied-id
	Compare::is_transparent is valid and denotes a type.
	If equal_range(u.first) == equal_range(k) is false, the behavior is  un-
     defined, where
	u is the new element to be inserted.

	No iterators or references are 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::map<std::string, std::unique_ptr<foo>>. In
     addition,
	try_emplace  treats  the  key and the arguments to the mapped_type sepa-
     rately, 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_map_try_emplace			   201411L	 (C++17)
     std::map::try_emplace,
								     std::map::in-
     sert_or_assign
								     Heteroge-
     neous overloads
								     for the re-
     maining member
       __cpp_lib_associative_heterogeneous_insertion 202311L  (C++26)  functions
     in ordered and
								     unordered
     associative
								     containers.
     Overloads (3)
								     and (6).

Example
     // Run this code

      #include <iostream>
      #include <string>
      #include <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::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);
      }

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
		     (since C++17)
		     (public member function)

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