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

NAME
     std::map::insert - std::map::insert

Synopsis
	std::pair<iterator, bool> insert( const value_type&  (1)
	value );
	template< class P >				     (2) (since C++11)
	std::pair<iterator, bool> insert( P&& value );
	std::pair<iterator, bool> insert( value_type&& value (3) (since C++17)
	);
	iterator      insert(	   iterator	 pos,	   const     value_type&
     (until C++11)
	value );
	iterator	insert(        const_iterator	      pos,	   const
     (since C++11)
	value_type& value );
	template<    class    P    >					     (5)
     (since C++11)
	iterator insert( const_iterator pos, P&& value );
	iterator   insert(   const_iterator   pos,    value_type&&	     (6)
     (since C++17)
	value );					     (4)
	template< class InputIt >				 (7)
	void insert( InputIt first, InputIt last );
	void	insert(    std::initializer_list<value_type>	ilist	     (8)
     (since C++11)
	);
	insert_return_type   insert(   node_type&&   nh    );		     (9)
     (since C++17)
	iterator   insert(   const_iterator   pos,   node_type&&   nh	    (10)
     (since C++17)
	);

	Inserts element(s) into the container, if the container doesn't  already
     contain an
	element with an equivalent key.

	1-3) Inserts value.
	Overload  (2)  is equivalent to emplace(std::forward<P>(value)) and only
     participates
	in overload resolution if std::is_constructible<value_type,  P&&>::value
     == true.
	4-6)  Inserts value in the position as close as possible to the position
     just prior
	to pos.
	Overload (5) is equivalent to emplace_hint(hint, std::forward<P>(value))
     and only
	participates in overload resolution if std::is_constructible<value_type,
     P&&>::value
	== true.
	7) Inserts elements from range [first, last). If  multiple  elements  in
     the range have
	keys  that  compare  equivalent,  it is unspecified which element is in-
     serted (pending
	LWG2844).
	8) Inserts elements from initializer list ilist. If multiple elements in
     the range
	have keys that compare equivalent, it is unspecified  which  element  is
     inserted
	(pending LWG2844).
	9)  If	nh is an empty node handle, does nothing. Otherwise, inserts the
     element owned
	by nh into the container , if the container doesn't already  contain  an
     element with
	a  key	equivalent  to	nh.key(). The behavior is undefined if nh is not
     empty and
	get_allocator() != nh.get_allocator().
	10) If nh is an empty node handle, does nothing and returns the end  it-
     erator.
	Otherwise,  inserts  the  element owned by nh into the container, if the
     container
	doesn't already contain an element with a key  equivalent  to  nh.key(),
     and returns
	the iterator pointing to the element with key equivalent to nh.key()(re-
     gardless of
	whether  the  insert succeeded or failed). If the insertion succeeds, nh
     is moved
	from, otherwise it retains ownership of the element. The element is  in-
     serted as
	close as possible to the position just prior to pos. The behavior is un-
     defined if nh
	is not empty and get_allocator() != nh.get_allocator().

	No iterators or references are invalidated.
	If  the  insertion is successful, pointers and references to the element
     obtained
	while it is held in the node handle are invalidated,  and  pointers  and
     references
	obtained to that element before it was extracted become valid.
	(since C++17)

Parameters
	pos	    - iterator to the position before which the new element will
     be inserted
	value	    - element value to insert
	first, last - range of elements to insert
	ilist	    - initializer list to insert the values from
	nh	    - a compatible node handle

Type requirements
	-
	InputIt must meet the requirements of LegacyInputIterator.

Return value
	1-3) A pair consisting of an iterator to the inserted element (or to the
     element
	that  prevented  the insertion) and a bool value set to true if and only
     if the
	insertion took place.
	4-6) An iterator to the inserted element, or to the  element  that  pre-
     vented the
	insertion.
	7,8) (none)
	9)  An object of insert_return_type with the members initialized as fol-
     lows:
	  * If nh is empty, inserted is false, position is end(),  and	node  is
     empty.
	  *  Otherwise	if  the insertion took place, inserted is true, position
     points to the
	    inserted element, and node is empty.
	  * If the insertion failed, inserted is false, node  has  the	previous
     value of nh,
	    and position points to an element with a key equivalent to nh.key().
	10) End iterator if nh was empty, iterator pointing to the inserted ele-
     ment if
	insertion  took  place,  and  iterator pointing to an element with a key
     equivalent to
	nh.key() if it failed.

Exceptions
	1-6) If an exception is thrown by any operation, the  insertion  has  no
     effect.

	 This section is incomplete
	 Reason: cases 7-10

Complexity
	1-3) Logarithmic in the size of the container, O(log(size())).
	4-6) Amortized constant if the insertion happens in the position just
	after
	(until C++11)
	before
	(since C++11) pos, logarithmic in the size of the container otherwise.
	7,8) O(NA.log(size() + N)), where N is the number of elements to insert.
	9) Logarithmic in the size of the container, O(log(size())).
	10) Amortized constant if the insertion happens in the position just be-
     fore pos,
	logarithmic in the size of the container otherwise.

Notes
	The hinted insert (4-6) does not return a boolean in order to be
	signature-compatible  with  positional	insert on sequential containers,
     such as
	std::vector::insert. This makes it possible to create generic  inserters
     such as
	std::inserter. One way to check success of a hinted insert is to compare
     size()
	before and after.

Example
     // Run this code

      #include <iomanip>
      #include <iostream>
      #include <map>
      #include <string>
      using namespace std::literals;

      template<typename It>
      void print_insertion_status(It it, bool success)
      {
	  std::cout << "Insertion of " << it->first
		    << (success ? " succeeded\n" : " failed\n");
      }

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

	  // Overload 3: insert from rvalue reference
	  const auto [it_hinata, success] = heights.insert({"Hinata"s, 162.8});
	  print_insertion_status(it_hinata, success);

	  {
	      // Overload 1: insert from lvalue reference
	      const auto [it, success2] = heights.insert(*it_hinata);
	      print_insertion_status(it, success2);
	  }
	  {
	      // Overload 2: insert via forwarding to emplace
	      const  auto  [it,  success] = heights.insert(std::pair{"Kageyama",
     180.6});
	      print_insertion_status(it, success);
	  }
	  {
	      // Overload 6: insert from rvalue reference with positional hint
	      const std::size_t n = std::size(heights);
	      const auto it = heights.insert(it_hinata, {"Azumane"s, 184.7});
	      print_insertion_status(it, std::size(heights) != n);
	  }
	  {
	      // Overload 4: insert from lvalue reference with positional hint
	      const std::size_t n = std::size(heights);
	      const auto it = heights.insert(it_hinata, *it_hinata);
	      print_insertion_status(it, std::size(heights) != n);
	  }
	  {
	      // Overload 5: insert via forwarding to  emplace	with  positional
     hint
	      const std::size_t n = std::size(heights);
	      const  auto it = heights.insert(it_hinata, std::pair{"Tsukishima",
     188.3});
	      print_insertion_status(it, std::size(heights) != n);
	  }

	  auto node_hinata = heights.extract(it_hinata);
	  std::map<std::string, float> heights2;

	  // Overload 7: insert from iterator range
	  heights2.insert(std::begin(heights), std::end(heights));

	  // Overload 8: insert from initializer_list
	  heights2.insert({{"Kozume"s, 169.2}, {"Kuroo", 187.7}});

	  // Overload 9: insert node
	  const auto status = heights2.insert(std::move(node_hinata));
	  print_insertion_status(status.position, status.inserted);

	  node_hinata = heights2.extract(status.position);
	  {
	      // Overload 10: insert node with positional hint
	      const std::size_t n = std::size(heights2);
	      const    auto    it    =	   heights2.insert(std::begin(heights2),
     std::move(node_hinata));
	      print_insertion_status(it, std::size(heights2) != n);
	  }

	  // Print resulting map
	  std::cout << std::left << '\n';
	  for (const auto& [name, height] : heights2)
	      std::cout << std::setw(10) << name << " | " << height << "cm\n";
      }

Output:
      Insertion of Hinata succeeded
      Insertion of Hinata failed
      Insertion of Kageyama succeeded
      Insertion of Azumane succeeded
      Insertion of Hinata failed
      Insertion of Tsukishima succeeded
      Insertion of Hinata succeeded
      Insertion of Hinata succeeded

      Azumane	 | 184.7cm
      Hinata	 | 162.8cm
      Kageyama	 | 180.6cm
      Kozume	 | 169.2cm
      Kuroo	 | 187.7cm
      Tsukishima | 188.3cm

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to	    Behavior as  published		 Correct
     behavior
								  the  insertion
     is required
			    pos was just a hint, it could be	  to
	LWG 233  C++98	    totally ignored			  be as close as
     possible to
								  the
								  position  just
     prior to pos
			    the  complexity  of  overload (7) was    removed the
     linear
	LWG 264  C++98	    required to be linear if		  requirement
			    the range [first, last) is sorted	  in  this  spe-
     cial case
			    according to Compare
			    in the return value of overload (1),
	LWG 316  C++98	    it was not specified		  success is
			    which  bool  value indicates a	    indicated by
     true
			    successful insertion
	LWG 2005 C++11	    overloads (2,5) were poorly described  improved  the
     description

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)
	insert_or_assign inserts an element or assigns to the current element if
     the key
	(C++17) 	 already exists
			 (public member function)
	inserter	  creates  a  std::insert_iterator of type inferred from
     the argument
			 (function template)

Category:
	  * Todo with reason

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