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

FreeBSD Manual Pages

  
 
  

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

NAME
       std::flat_map::try_emplace - std::flat_map::try_emplace

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

	  If a key equivalent to k already exists in the container, does noth-
       ing. Otherwise,
	  inserts  a  new  element into	the underlying containers c with key k
       and value
	  constructed with args.

	  1,2,4,5) Equivalent to:

	auto key_it = ranges::upper_bound(c.keys, k, compare);
	auto  value_it	=  c.values.begin()  +	 std::distance(c.keys.begin(),
       key_it);
	c.keys.insert(key_it, std::forward<decltype(k)>(k));
	c.values.emplace(value_it, std::forward<Args>(args)...);

	  3,6) Equivalent to:

	auto key_it = ranges::upper_bound(c.keys, k, compare);
	auto   value_it	 =  c.values.begin()  +	 std::distance(c.keys.begin(),
       key_it);
	c.keys.emplace(key_it, std::forward<K>(k));
	c.values.emplace(value_it, std::forward<Args>(args)...);

	  The conversion from k	into key_type must construct an	object u,  for
       which find(k) ==
	  find(u) is true. Otherwise, the behavior is undefined.
	  These	overloads participate in overload resolution only if :
	    *  The qualified-id	Compare::is_transparent	is valid and denotes a
       type.
	    * std::is_constructible_v<key_type,	K> is true.
	    * std::is_assignable_v<mapped_type&, Args...> is true.
	    * For (3) only, std::is_convertible_v<K&&, const_iterator> and
	      std::is_convertible_v<K&&, iterator> are both false.

	   Information on iterator invalidation	is copied from here

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-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
       arguments if the
	  insertion  does  not	happen,	which makes it easy to manipulate maps
       whose values are
	  move-only	types,	   such	    as	    std::flat_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).

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

Example
       // Run this code

	#include <flat_map>
	#include <iostream>
	#include <string>
	#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
			   (public member function)
	  emplace_hint	   constructs elements in-place	using a	hint
			   (public member function)
	  insert	   inserts elements
			   (public member function)
			   inserts  an	element	or assigns to the current ele-
       ment if the key
	  insert_or_assign already exists
			   (public member function)

http://cppreference.com		  2024.06.10	 std::flat_map::try_emplace(3)

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

home | help