std::forward_list::splice_after(3)

NAME
std::forward_list::splice_after - std::forward_list::splice_after

Synopsis
   void splice_after( const_iterator pos, forward_list& other ); (1) (since C++11)
   void splice_after( const_iterator pos, forward_list&& other ); (1) (since C++11)
   void splice_after( const_iterator pos, forward_list& other, (2) (since C++11)
   const_iterator it );
   void splice_after( const_iterator pos, forward_list&& other, (2) (since C++11)
   const_iterator it );
   void splice_after( const_iterator pos, forward_list& other, (3) (since C++11)
   const_iterator first, const_iterator last );
   void splice_after( const_iterator pos, forward_list&& other, (3) (since C++11)
   const_iterator first, const_iterator last );
   Moves elements from another forward_list to *this.
   No elements are copied. pos must be either a deferenceable valid iterator into *this
   or the before_begin() iterator (in particular, end() is not a valid argument for
   pos). The behavior is undefined if get_allocator() != other.get_allocator(). No
   iterators or references become invalidated, the iterators to the moved elements now
   refer into *this, not into other.
   1) Moves all elements from other into *this. The elements are inserted after the
   element pointed to by pos. The container other becomes empty after the operation.
   The behavior is undefined if other refers to the same object as *this.
   2) Moves the element pointed to by the iterator following it from other into *this.
   The element is inserted after the element pointed to by pos. Has no effect if
   pos==it or if pos==++it.
   3) Moves the elements in the range (first, last) from other into *this. The elements
   are inserted after the element pointed to by pos. The element pointed-to by first is
   not moved. The behavior is undefined if pos is an iterator in the range
   (first,last).

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

Return value
   (none)

Exceptions
   Throws nothing.

Complexity
   1) Linear in the size of other
   2) Constant
   3) Linear in std::distance(first, last)

Example
   Demonstrates the meaning of open interval (first, last) in the third form of
   splice_after(): the first element of l1 is not moved. // Run this code
 #include <algorithm>
 #include <cassert>
 #include <forward_list>
 #include <initializer_list>
 #include <iostream>
 using F = std::forward_list<int>;
 std::ostream& operator<< (std::ostream& os, F const& l) {
     for (int e : l) os << e << ' ';
     return os;
 }
 int main()
 {
     {
         F l1 = { 1, 2, 3, 4, 5 };
         F l2 = { 10, 11, 12 };
         l2.splice_after(l2.cbegin(), l1, l1.cbegin(), l1.cend());
         // not equivalent to l2.splice_after(l2.cbegin(), l1);
         // which is equivalent to
         // l2.splice_after(l2.cbegin(), l1, l1.cbefore_begin(), l1.end());
         std::cout << "l1: " << l1 << "\n"
                      "l2: " << l2 << '\n';
     }
     // Compare two given lists and abort the program if they are not equal.
     auto equ = [] (F const& p, std::initializer_list<int> const& q) {
         assert(std::ranges::equal(p, q));
     };
     // The following code demonstrates all three overloads (1),..(3).
     {
         F x = { 1, 2, 3, 4, 5 };
         F y = { 10, 11, 12 };
         x.splice_after(x.cbegin(), y); // (1)
         equ( x, { 1, 10, 11, 12, 2, 3, 4, 5 } );
         equ( y, { } );
     }
     {
         F x = { 1, 2, 3, 4, 5 };
         F y = { 10, 11, 12 };
         x.splice_after(x.cbegin(), y, y.cbegin()); // (2)
         equ( x, { 1, 11, 2, 3, 4, 5 } );
         equ( y, { 10, 12 } );
     }
     {
         F x = { 1, 2, 3, 4, 5 };
         F y = { 10, 11, 12 };
         x.splice_after(x.cbegin(), y, y.cbegin(), y.cend()); // (3)
         equ( x, { 1, 11, 12, 2, 3, 4, 5 } );
         equ( y, { 10 } );
     }
 }

Output:
 l1: 1
 l2: 10 2 3 4 5 11 12

See also
   merge merges two sorted lists
   (C++11) (public member function)
   remove removes elements satisfying specific criteria
   remove_if (public member function)
   (C++11)
   before_begin returns an iterator to the element before beginning
   cbefore_begin (public member function)
   (C++11)