C++ <list> - splice() Function

The C++ list::splice function is used to transfer elements from one list to another. This function has following versions:

The first version (1) transfers all elements from other into *this. The elements are inserted before the element pointed to by position. The container other becomes empty after the operation. The behavior is undefined if other refers to the same object as *this.
The first version (2) transfers the element pointed to by it from other into *this. The element is inserted before the element pointed to by position.
The first version (3) transfers the elements in the range [first, last) from other into *this. The elements are inserted before the element pointed to by position. The behavior is undefined if position is an iterator in the range [first,last).

//entire list (1)
void splice (iterator position, list& other);
  
//single element (2)
void splice (iterator position, list& other, iterator i);

//range of elements (3)
void splice (iterator position, list& other, iterator first, iterator last);

//entire list (1)
void splice (const_iterator position, list& other);
void splice (const_iterator position, list&& other);

//single element (2)
void splice (const_iterator position, list& other, const_iterator it);
void splice (const_iterator position, list&& other, const_iterator it);

//range of elements (3)
void splice (const_iterator position, list& other,
             const_iterator first, const_iterator last);
void splice (const_iterator position, list&& other,
             const_iterator first, const_iterator last);

Parameters

`position`	Specify the position in the list where the elements of other are inserted.
`other`	Specify a list object to transfer the content from.
`it`	Specify Iterator to an element in other. Only this single element will be transferred.
`first`	Specify the starting position of Iterator in other. Transfers of the elements in the range [first,last) to position.
`last`	Specify the last position of Iterator in other. Transfers of the elements in the range [first,last) to position.

Note: Member types iterator and const_iterator are bidirectional iterator types that point to elements.

Return Value

None.

Time Complexity

Constant i.e, Θ(1) for version (1) and (2).
Up to Linear i.e, Θ(n) for version (3)..

Example: transfer all elements of a list

In the example below, the list::splice function is used to transfer all elements from one list to another.

#include <iostream>
#include <list>
using namespace std;
 
int main (){
  list<int> list1{1, 2, 3, 4, 5};
  list<int> list2{10, 20, 30, 40, 50};

  list<int>::iterator it;

  cout<<"list1 contains: ";
  for(it = list1.begin(); it != list1.end(); it++)
    cout<<*it<<" ";
  
  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); it++)
    cout<<*it<<" ";  

  //transfers all elements of list2 into list1
  list1.splice(list1.begin(), list2);

  cout<<"\n\nlist1 contains: ";
  for(it = list1.begin(); it != list1.end(); it++)
    cout<<*it<<" ";
  
  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); it++)
    cout<<*it<<" ";

  return 0;
}

The output of the above code will be:

list1 contains: 1 2 3 4 5 
list2 contains: 10 20 30 40 50 

list1 contains: 10 20 30 40 50 1 2 3 4 5 
list2 contains:

Example: transfer a single element of a list

Consider the example below where this function is used to transfer a single element from one list to another.

#include <iostream>
#include <list>
using namespace std;
 
int main (){
  list<int> list1{1, 2, 3, 4, 5};
  list<int> list2{10, 20, 30, 40, 50};

  list<int>::iterator it;

  cout<<"list1 contains: ";
  for(it = list1.begin(); it != list1.end(); it++)
    cout<<*it<<" ";
  
  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); it++)
    cout<<*it<<" ";  

  it = list2.begin();
  it++;

  //transfers a single element of list2 into list1
  list1.splice(list1.begin(), list2, it);

  cout<<"\n\nlist1 contains: ";
  for(it = list1.begin(); it != list1.end(); it++)
    cout<<*it<<" ";
  
  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); it++)
    cout<<*it<<" ";

  return 0;
}

The output of the above code will be:

list1 contains: 1 2 3 4 5 
list2 contains: 10 20 30 40 50 

list1 contains: 20 1 2 3 4 5 
list2 contains: 10 30 40 50

Example: transfer a range of elements of a list

Consider one more example where this function is used to transfer a range of elements from one list to another.

#include <iostream>
#include <list>
using namespace std;
 
int main (){
  list<int> list1{1, 2, 3, 4, 5};
  list<int> list2{10, 20, 30, 40, 50};

  list<int>::iterator it;

  cout<<"list1 contains: ";
  for(it = list1.begin(); it != list1.end(); it++)
    cout<<*it<<" ";
  
  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); it++)
    cout<<*it<<" ";  

  it = list2.begin();
  advance(it, 2);

  //transfers a single element of list2 into list1
  list1.splice(list1.begin(), list2, it, list2.end());

  cout<<"\n\nlist1 contains: ";
  for(it = list1.begin(); it != list1.end(); it++)
    cout<<*it<<" ";
  
  cout<<"\nlist2 contains: ";
  for(it = list2.begin(); it != list2.end(); it++)
    cout<<*it<<" ";

  return 0;
}

The output of the above code will be:

list1 contains: 1 2 3 4 5 
list2 contains: 10 20 30 40 50 

list1 contains: 30 40 50 1 2 3 4 5 
list2 contains: 10 20

❮ C++ <list> Library