list::splice


public member function
void splice ( iterator position, list<T,Allocator>& x );
void splice ( iterator position, list<T,Allocator>& x, iterator i );
void splice ( iterator position, list<T,Allocator>& x, iterator first, iterator last );

Move elements from list to list

Moves elements from list x into the list container at the specified position, effectively inserting the specified elements into the container and removing them from x.

This increases the container size by the amount of elements inserted, and reduces the size of x by the same amount ( whenever x is not the same as *this ).

The operation does not involve the construction or destruction of any element object and, except for the third version, it is performed in constant time.

The iterators that pointed to moved elements are no longer valid.

Parameters

position
Position within the container where the elements of x are inserted.
iterator is a member type, defined as a bidirectional iterator.
x
A list object containing the same type of objects as this container.
This parameter may be *this if position points to an element not actually being spliced: for the first version, this is never the case, but for the other versions this is possible.
i
Iterator to an element in x. Only this single element is moved.
iterator is a member type, defined as a bidirectional iterator type.
first,last
Iterators specifying a range of elements in x. Moves the elements in the range [first,last) to position.
Notice that the range includes all the elements between first and last, including the element pointed by first but not the one pointed by last.
iterator is a member type, defined as a bidirectional iterator type.


Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
// splicing lists
#include <iostream>
#include <list>
using namespace std;

int main ()
{
  list<int> mylist1, mylist2;
  list<int>::iterator it;

  // set some initial values:
  for (int i=1; i<=4; i++)
     mylist1.push_back(i);      // mylist1: 1 2 3 4

  for (int i=1; i<=3; i++)
     mylist2.push_back(i*10);   // mylist2: 10 20 30

  it = mylist1.begin();
  ++it;                         // points to 2

  mylist1.splice (it, mylist2); // mylist1: 1 10 20 30 2 3 4
                                // mylist2 (empty)
                                // "it" still points to 2 (the 5th element)
                                          
  mylist2.splice (mylist2.begin(),mylist1, it);
                                // mylist1: 1 10 20 30 3 4
                                // mylist2: 2
                                // "it" is now invalid.
  it = mylist1.begin();
  advance(it,3);                // "it" points now to 30

  mylist1.splice ( mylist1.begin(), mylist1, it, mylist1.end());
                                // mylist1: 30 3 4 1 10 20

  cout << "mylist1 contains:";
  for (it=mylist1.begin(); it!=mylist1.end(); it++)
    cout << " " << *it;

  cout << "\nmylist2 contains:";
  for (it=mylist2.begin(); it!=mylist2.end(); it++)
    cout << " " << *it;
  cout << endl;

  return 0;
}

Output:
mylist1 contains: 30 3 4 1 10 20
mylist2 contains: 2


Complexity

Constant on all cases, except when x is a list object different than *this in the third function version, in which case it is linear in the range between first and last (iterator advance).

See also

list::insert Insert elements (public member function)
list::merge Merge sorted lists (public member function)
list::erase Erase elements (public member function)