home | help 
std::list::splice(3)	       C++ Standard Libary	    std::list::splice(3)

NAME
     std::list::splice - std::list::splice

Synopsis
	void splice( const_iterator pos, list& other ); 		   (1)
	void  splice(  const_iterator pos, list&& other );		     (2)
     (since C++11)
	void splice( const_iterator pos, list& other, const_iterator it ); (3)
	void splice( const_iterator pos, list&& other, const_iterator  it    (4)
     (since C++11)
	);
	void splice( const_iterator pos, list& other,			   (5)
		     const_iterator first, const_iterator last);
	void  splice(  const_iterator pos, list&& other,		     (6)
     (since C++11)
		     const_iterator first, const_iterator last );

	Transfers elements from one list to another.

	No elements are copied or moved, only the internal pointers of the  list
     nodes are
	re-pointed. No iterators or references become invalidated, the iterators
     to moved
	elements remain valid, but now refer into *this, not into other.

	1,2)  Transfers all elements from other into *this. The elements are in-
     serted before
	the element pointed to by pos. The container other becomes  empty  after
     the
	operation.
	3,4)  Transfers  the element pointed to by it from other into *this. The
     element is
	inserted before the element pointed to by pos.
	5,6) Transfers the elements in the range [first, last) from  other  into
     *this. The
	elements are inserted before the element pointed to by pos.

	The behavior is undefined if

	  * get_allocator() != other.get_allocator(),
	  * for overloads (1,2), *this and other refer to the same object,
	  *  for  overloads  (3,4),  it  is  not a dereferenceable iterator into
     other, or
	  * for overloads (5,6),

	  * [first, last) is not a valid range in other, or
	  * pos is in [first, last).

Parameters
	pos	    - element before which the content will be inserted
	other	    - another container to transfer the content from
	it	    - the element to transfer from other to *this
	first, last - the range of elements to transfer from other to *this

Return value
	(none)

Exceptions
	Throws nothing.

Complexity
	1-4) Constant.
	5,6) Constant if other refers to the same  object  as  *this,  otherwise
     linear in
	std::distance(first, last).

Example
     // Run this code

      #include <iostream>
      #include <list>

      std::ostream& operator<<(std::ostream& ostr, const std::list<int>& list)
      {
	  for (auto& i : list)
	      ostr << ' ' << i;

	  return ostr;
      }

      int main ()
      {
	  std::list<int> list1{1, 2, 3, 4, 5};
	  std::list<int> list2{10, 20, 30, 40, 50};

	  auto it = list1.begin();
	  std::advance(it, 2);

	  list1.splice(it, list2);

	  std::cout << "list1:" << list1 << '\n';
	  std::cout << "list2:" << list2 << '\n';

	  list2.splice(list2.begin(), list1, it, list1.end());

	  std::cout << "list1:" << list1 << '\n';
	  std::cout << "list2:" << list2 << '\n';
      }

Output:
      list1: 1 2 10 20 30 40 50 3 4 5
      list2:
      list1: 1 2 10 20 30 40 50
      list2: 3 4 5

	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
			   references  and  iterators to the moved    they refer
     or point to
	LWG 250 C++98	   element(s) were all invalidated	    the
								    same    ele-
     ment(s) in *this
	N2525	C++98	   O(1) splicing could not be guaranteed if the behavior
     is
			   get_allocator() != other.get_allocator() undefined in
     this case

See also
	merge	  merges two sorted lists
		  (public member function)
	remove	  removes elements satisfying specific criteria
	remove_if (public member function)

http://cppreference.com 	   2024.06.10		    std::list::splice(3)
home | help