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

Moves elements from another forward_list to *this. The elements are inserted after
the element pointed to by pos.

No elements are copied. No iterators or references become invalidated. The iterators
to the moved elements now refer into *this, not into other.

1,2) Moves all elements from other into *this. The container other becomes empty
after the operation.
3,4) Moves the element pointed to by the iterator following it from other into
*this. Has no effect if pos == it or if pos == ++it.
5,6) Moves the elements in the range (first, last) from other into *this. The
element pointed-to by first is not moved.

The behavior is undefined if

* get_allocator() != other.get_allocator(),
* pos is neither before_begin() nor a dereferenceable iterator in
[begin(), end()),
* for overloads (1,2), *this and other refer to the same object,
* for overloads (3,4), the iterator following it is not a dereferenceable iterator
into other, or
* for overloads (5,6),

* (first, last) is not a valid range in other,
* some iterators in (first, last) are not dereferenceable, or
* pos is in (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,2) Linear in the size of other.
3,4) Constant.
5,6) Linear in std::distance(first, last).

Example¶

// Run this code

#include <cassert>
#include <forward_list>

int main()
{
using F = std::forward_list<int>;

// Demonstrate the meaning of open range (first, last)
// in overload (5): the first element of l1 is not moved.
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());

assert((l1 == F{1}));
assert((l2 == F{10, 2, 3, 4, 5, 11, 12}));

// Overload (1)
F x = {1, 2, 3, 4, 5};
F y = {10, 11, 12};
x.splice_after(x.cbegin(), y);
assert((x == F{1, 10, 11, 12, 2, 3, 4, 5}));
assert((y == F{}));

// Overload (3)
x = {1, 2, 3, 4, 5};
y = {10, 11, 12};
x.splice_after(x.cbegin(), y, y.cbegin());
assert((x == F{1, 11, 2, 3, 4, 5}));
assert((y == F{10, 12}));

// Overload (5)
x = {1, 2, 3, 4, 5};
y = {10, 11, 12};
x.splice_after(x.cbegin(), y, y.cbegin(), y.cend());
assert((x == F{1, 11, 12, 2, 3, 4, 5}));
assert((y == F{10}));
}

Defect reports

The following behavior-changing defect reports were applied retroactively to
previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 2045 C++11 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)
before_begin returns an iterator to the element before beginning
cbefore_begin (public member function)