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

FreeBSD Manual Pages

  
 
  

home | help 
std::map::insert_or_assign(3) C++ Standard Libarystd::map::insert_or_assign(3)

NAME
       std::map::insert_or_assign - std::map::insert_or_assign

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

	  1,4)	If  a key equivalent to	k already exists in the	container, as-
       signs
	  std::forward<M>(obj) to the mapped_type corresponding	to the key  k.
       If the key does
	  not  exist,  inserts	the new	value as if by insert, constructing it
       from value_type(k,
	  std::forward<M>(obj)).
	  2,5) Same as (1,4), except the mapped	value is constructed from
	  value_type(std::move(k), std::forward<M>(obj)).
	  3,6) If a key	equivalent to k	already	exists in the  container,  as-
       signs
	  std::forward<M>(obj)	to the mapped_type corresponding to the	key k.
       If the key does
	  not exist, constructs	an  object  u  of  value_type  with  std::for-
       ward<K>(k),
	  std::forward<M>(obj)),    then    inserts    u    into   *this.   If
       equal_range(u.first) ==
	  equal_range(k) is false, the behavior	is undefined.  The  value_type
       must be
	  EmplaceConstructible	into  map  from	 std::forward<K>(k), std::for-
       ward<M>(obj). This
	  overload participates	in overload resolution only if the  qualified-
       id
	  Compare::is_transparent is valid and denotes a type. It allows call-
       ing this	function
	  without constructing an instance of Key.

	  The behavior is undefined
	  (until C++20)
	  The program is ill-formed
	  (since C++20)	if std::is_assignable_v<mapped_type&, M&&> is false.

	  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
       inserted
	  obj  - the value to insert or	assign

Return value
	  1-3)	The  bool  component  is  true if the insertion	took place and
       false if	the
	  assignment took place. The iterator component	is pointing at the el-
       ement that was
	  inserted or updated.
	  4-6) Iterator	pointing at the	element	that was inserted or updated.

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

Notes
	  insert_or_assign returns more	information than operator[]  and  does
       not require
	  default-constructibility of the mapped type.

		      Feature-test     macro		       Value	   Std
       Feature
	 __cpp_lib_map_try_emplace			   201411L     (C++17)
       std::map::try_emplace,
								       std::map::in-
       sert_or_assign
								       Hetero-
       geneous overloads
								       for the
       remaining member
	 __cpp_lib_associative_heterogeneous_insertion	202311L	 (C++26) func-
       tions in	ordered	and
								       un-
       ordered associative
								       con-
       tainers.	Overloads (3)
								       and
       (6).

Example
       // Run this code

	#include <iostream>
	#include <string>
	#include <map>

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

	void print_result(auto const& pair)
	{
	    std::cout << (pair.second ?	"inserted: " : "assigned: ");
	    print_node(*pair.first);
	}

	int main()
	{
	    std::map<std::string, std::string> myMap;

	    print_result(myMap.insert_or_assign("a", "apple"));
	    print_result(myMap.insert_or_assign("b", "banana"));
	    print_result(myMap.insert_or_assign("c", "cherry"));
	    print_result(myMap.insert_or_assign("c", "clementine"));

	    for	(const auto& node : myMap)
		print_node(node);
	}

Output:
	inserted: [a] =	apple
	inserted: [b] =	banana
	inserted: [c] =	cherry
	assigned: [c] =	clementine
	[a] = apple
	[b] = banana
	[c] = clementine

See also
	  operator[] access or insert specified	element
		     (public member function)
	  at	     access specified element with bounds checking
		     (public member function)
		     inserts elements
	  insert     or	nodes
		     (since C++17)
		     (public member function)
	  emplace    constructs	element	in-place
	  (C++11)    (public member function)

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

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

home | help