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

NAME
     std::flat_set::insert - std::flat_set::insert

Synopsis
	std::pair<iterator,  bool>  insert(  const value_type& value );      (1)
     (since C++23)
	std::pair<iterator, bool> insert( value_type&&	value  );	     (2)
     (since C++23)
	iterator  insert(  const_iterator  pos, const value_type& value );   (3)
     (since C++23)
	iterator insert( const_iterator pos, value_type&&  value  );	     (4)
     (since C++23)
	template<  class  K  >						     (5)
     (since C++23)
	iterator insert( const_iterator pos, K&& x );
	template< class  InputIt  >					     (6)
     (since C++23)
	void insert( InputIt first, InputIt last );
	template<  class  K  >						     (7)
     (since C++23)
	std::pair<iterator, bool> insert( K&& x );
	template< class  InputIt  >					     (8)
     (since C++23)
	void insert( std::sorted_unique_t, InputIt first, InputIt last );
	void  insert(  std::initializer_list<key_type>	ilist );	     (9)
     (since C++23)
	void insert( std::sorted_unique_t  s,				    (10)
     (since C++23)
	std::initializer_list<key_type> ilist );

	Inserts element(s) into the container, if the container does not already
     contain an
	element with an equivalent key.

	1) Inserts value. Equivalent to return emplace(value);.
	2) Inserts value. Equivalent to return emplace(std::move(value));.
	3)  Inserts  value  in the position as close as possible to the position
     just prior to
	pos. Equivalent to return emplace_hint(pos, value);.
	4) Inserts value in the position as close as possible  to  the	position
     just prior to
	pos. Equivalent to return emplace_hint(pos, std::move(value));.
	5,7)  If  *this already contains an element which transparently compares
     equivalent to
	x, does nothing. Otherwise, inserts a new element as if by:
	  * (5) emplace(pos, std::forward<K>(x)) (in the position  as  close  as
     possible to
	    the position just prior to pos);
	  * (7) emplace(std::forward<K>(x)).
	The  conversion  from  x  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, and
	  * std::is_constructible_v<value_type, K> is true,
	which  together allows calling this function without constructing an in-
     stance of Key.
	6) Equivalent to the sequence of operations:
	 1. Inserts elements from range [first, last) as if by c.insert(c.end(),
     first,
	    last);.
	 2. Sorts the range of newly inserted elements with respect to compare.
	 3. Merges the resulting sorted range and the sorted range of pre-exist-
     ing elements
	    into a single sorted range. (Note: the merge operation may	allocate
     memory).
	 4.  Erases  all  but  the  first element from each group of consecutive
     equivalent
	    elements.
	If multiple elements in the range have keys that compare equivalent,  it
     is
	unspecified which element is inserted (pending LWG2844).
	8)  Inserts  elements  from  range  [first,  last).  Equivalent  to  in-
     sert(first, last);.
	If multiple elements in the range have keys that compare equivalent,  it
     is
	unspecified which element is inserted (pending LWG2844).
	9)  Inserts  elements  from  initializer  list	ilist. Equivalent to in-
     sert(ilist.begin(),
	ilist.end());.
	If multiple elements in the range have keys that compare equivalent,  it
     is
	unspecified which element is inserted (pending LWG2844).
	10)  Inserts  elements	from  initializer  list ilist. Equivalent to in-
     sert(s,
	ilist.begin(), ilist.end());.
	If multiple elements in the range have keys that compare equivalent,  it
     is
	unspecified which element is inserted (pending LWG2844).

	 Information on iterator invalidation is copied from here

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
	x	     -	a  value  of any type that can be transparently compared
     with a key
	s	    - a disambiguation tag indicating that the input sequence is
     sorted
		      (with respect to compare) and contains  only  unique  ele-
     ments

Type requirements
	-
	InputIt must meet the requirements of LegacyInputIterator.

Return value
	1,2) 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.
	3-5) An iterator to the inserted element, or to the  element  that  pre-
     vented the
	insertion.
	6) (none)
	7)  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.
	8-10) (none)

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

	 This section is incomplete
	 Reason: cases 6,8-10

Complexity
	1-5) Linear in size().
	6) N + MA.log(M), where N is the size() before the operation and M is
	std::distance(first, last).
	7) Linear in size().
	8) Linear in N, where N is size() after the operation.
	9)  N  +  MA.log(M), where N is the size() before the operation and M is
     ilist.size().
	10) Linear in N, where N is size() after the operation.

	 This section is incomplete
	 Reason: recheck the complexity: 1-5, 7, 9, 10. The  lookup  is  log(N),
     but insertion
	 in underlying container is N/2 on average => Linear.

Notes
	The hinted insert (3-5) 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 <cassert>
      #include <flat_set>
      #include <iostream>

      int main()
      {
	  std::flat_set<int> set;

	  auto result_1 = set.insert(3);
	  assert(result_1.first != set.end()); // it is a valid iterator
	  assert(*result_1.first == 3);
	  if (result_1.second)
	      std::cout << "insert done\n";

	  auto result_2 = set.insert(3);
	  assert(result_2.first == result_1.first); // the same iterator
	  assert(*result_2.first == 3);
	  if (!result_2.second)
	      std::cout << "no insertion\n";
      }

Output:
      insert done
      no insertion

See also
	emplace      constructs element in-place
		     (public member function)
	emplace_hint constructs elements in-place using a hint
		     (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::flat_set::insert(3)
home | help