std::forwar...splice_after(3)

💅 std::forwar...splice_after(3) 💅

okay bestie, welcome to the C++ Standard Libary page for std::forward_list::splice_after — yes, the manual name is literally “C++ Standard Libary,” typo and all, we don’t fix icons here. This is the friend-group move operation for singly linked lists: it relocates nodes from one forward_list into another without copying anything. No cap. ✨

🌸 NAME 🌸

std::forward_list::splice_after — std::forward_list::splice_after

✨ Synopsis ✨

Six overloads, all (since C++11) — here they are in their exact natural habitat:

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.

🚨 hard warning, bestie: the behavior is undefined if any of these are true. This is not a vibe, this is UB: - 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. Iconic behavior, honestly.

🔥 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.

• LWG 2045 — applied to C++11; behavior as published: O(1) splicing could not be guaranteed if the get_allocator() != other.get_allocator(); correct behavior: behavior is 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)

---

that’s the whole page, bestie 💖 source is http://cppreference.com, version date 2024.06.10, page std::forwar...splice_after(3) — mwah 💋