std::list::splice(3)

✨ NAME ✨

hey bestie 💖 this is std::list::splice(3) from the C++ Standard Libary manual, and we're about to make list splicing make sense, fr fr. it's literally the std::list::splice function and it's giving pointer magic 👑

🌸 Synopsis 🌸

okay so here's the whole overload situation, exact vibes only:

     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 );

okay so the actual tea ☕: this 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. iykyk 💅

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

⚠️ bestie, 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) — like, nothing comes back, bestie. it's giving void energy ✨

🔥 Exceptions 🔥

Throws nothing. not a single exception, periodt 💀

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

• LWG 250 — applied to C++98. Behavior as published: references and iterators to the moved element(s) were all invalidated. Correct behavior: they refer or point to the same element(s) in *this.
• N2525 — applied to C++98. Behavior as published: O(1) splicing could not be guaranteed if 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)

---

okay that's the whole page bestie 💖 footer vibes: source http://cppreference.com, version/date 2024.06.10, page std::list::splice(3) — and that's on periodt ✨💅