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 inserted 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 retroactively 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 element(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)