std::list<T,Allocator>::splice

From cppreference.com
< cpp‎ | container‎ | list
 
 
 
 
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,
             const_iterator first, const_iterator last);
(5)
void splice( const_iterator pos, list&& other,
             const_iterator first, const_iterator last );
(6) (since C++11)

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.

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 [firstlast) from other into *this. The elements are inserted before the element pointed to by pos.

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 valid dereferenceable iterator of other,
  • for overloads (5,6), [firstlast) is not a valid range in other, or
  • for overloads (5,6), pos is in [firstlast).

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)

Exceptions

Throws nothing.

Complexity

1-4) Constant.
5,6) Constant if other refers to the same object as *this, otherwise linear in std::distance(first, last).

Example

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

DR Applied to Behavior as published Correct behavior
LWG 250 C++98 references and iterators to the moved
element(s) were all invalidated
they refer or point to the
same element(s) in *this
N2525 C++98 O(1) splicing could not be guaranteed if
get_allocator() != other.get_allocator()
the behavior is
undefined in this case

See also

merges two sorted lists
(public member function)
removes elements satisfying specific criteria
(public member function)