Namespaces
Variants

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

From cppreference.net
C++
Containers library
std::list
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
void splice ( const_iterator pos, list & other ) ;
(1) (constexpr since C++26)
void splice ( const_iterator pos, list && other ) ;
(2) (since C++11)
(constexpr since C++26)
void splice ( const_iterator pos, list & other, const_iterator it ) ;
(3) (constexpr since C++26)
void splice ( const_iterator pos, list && other, const_iterator it ) ;
(4) (since C++11)
(constexpr since C++26)
void splice ( const_iterator pos, list & other,
const_iterator first, const_iterator last ) ;
(5) (constexpr since C++26)
void splice ( const_iterator pos, list && other,
const_iterator first, const_iterator last ) ;
(6) (since C++11)
(constexpr since C++26)

Transfers elements from other to * this . The elements are inserted at pos .

If any of the following conditions is satisfied, the behavior is undefined:

  • pos is not in the range [ begin ( ) , end ( ) ) .
  • get_allocator ( ) == other. get_allocator ( ) is false .
1,2) Transfers all elements of other . other becomes empty after the operation.
If * this and other refer to the same object, the behavior is undefined.
3,4) Transfers the element pointed to by it .
* this and other can refer to the same object. In this case, there is no effect if pos == it or pos == ++ it is true .
If it is not in the range [ begin ( ) , end ( ) ) , the behavior is undefined.
5,6) Transfers elements in the range [ first , last ) .
* this and other can refer to the same object.
If any of the following conditions is satisfied, the behavior is undefined:
  • [ first , last ) is not a valid range in other ,
  • Any iterator in [ first , last ) is not dereferenceable.
  • pos is in [ first , last ) .

No iterators or references become invalidated. If * this and other refer to different objects, the iterators to the transferred elements now refer into * this , not into other .

Contents

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 pair of iterators defining the range of elements to transfer from other to * this

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.

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)