std::forward_list<T,Allocator>::splice_after

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Execution support library (C++26)

Technical specifications

Symbols index

External libraries

 

Containers library

Sequence

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

deque

forward_list (C++11)

list

Associative

set

multiset

map

multimap

Unordered associative

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

Adaptors

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

Views

span (C++20)

mdspan (C++23)

Tables

Iterator invalidation

Member function table

Non-member function table

 

std::forward_list

Member functions
forward_list::forward_list forward_list::~forward_list forward_list::operator= forward_list::assign forward_list::assign_range (C++23)   forward_list::get_allocator Element access forward_list::front Iterators forward_list::before_beginforward_list::cbefore_begin forward_list::beginforward_list::cbegin forward_list::endforward_list::cend Capacity forward_list::empty forward_list::max_size	Modifiers forward_list::clear forward_list::emplace_front forward_list::push_front forward_list::insert_after forward_list::emplace_after forward_list::erase_after forward_list::insert_range_after (C++23) forward_list::prepend_range (C++23) forward_list::pop_front forward_list::resize forward_list::swap Operations forward_list::merge forward_list::splice_after forward_list::removeforward_list::remove_if forward_list::reverse forward_list::unique forward_list::sort
Non-member functions
operator==operator<=> (C++20) swap(std::forward_list) erase(std::forward_list)erase_if(std::forward_list) (C++20)(C++20)	operator!=operator<operator>operator<=operator>= (until C++20)(until C++20)(until C++20)(until C++20)(until C++20)
Deduction guides (C++17)

 

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,                    const_iterator it );	(2)	(since C++11)
void splice_after( const_iterator pos, forward_list&& other,                    const_iterator it );	(2)	(since C++11)
void splice_after( const_iterator pos, forward_list& other,                    const_iterator first, const_iterator last );	(3)	(since C++11)
void splice_after( const_iterator pos, forward_list&& other,                    const_iterator first, const_iterator last );	(3)	(since C++11)

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 (public member function)
removeremove_if	removes elements satisfying specific criteria (public member function)
before_begincbefore_begin	returns an iterator to the element before beginning (public member function)