public member function
<list>
std::list::splice
| entire list (1) |
void splice (iterator position, list& x);
|
|---|
| single element (2) |
void splice (iterator position, list& x, iterator i);
|
|---|
| element range (3) |
void splice (iterator position, list& x, iterator first, iterator last);
|
|---|
| entire list (1) |
void splice (const_iterator position, list& x);
void splice (const_iterator position, list&& x);
|
|---|
| single element (2) |
void splice (const_iterator position, list& x, const_iterator i);
void splice (const_iterator position, list&& x, const_iterator i);
|
|---|
| element range (3) |
void splice (const_iterator position, list& x,
const_iterator first, const_iterator last);
void splice (const_iterator position, list&& x,
const_iterator first, const_iterator last); |
|---|
Transfer elements from list to list
Transfers elements from x into the container, inserting them at position.
This effectively inserts those elements into the container and removes them from x, altering the sizes of both containers. The operation does not involve the construction or destruction of any element. They are transferred, no matter whether x is an lvalue or an rvalue, or whether the value_type supports move-construction or not.
The first version (1) transfers all the elements of x into the container.
The second version (2) transfers only the element pointed by i from x into the container.
The third version (3) transfers the range [first,last) from x into the container.
Parameters
- position
- Position within the container where the elements of x are inserted.
Member types iterator and const_iterator are bidirectional iterator types that point to elements.
- x
- A list object of the same type (i.e., with the same template parameters, T and Alloc).
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 transferred.
iterator is a member type, defined as a bidirectional iterator type.
Member types iterator and const_iterator are bidirectional iterator types that point to elements.
- first,last
- Iterators specifying a range of elements in x. Transfers 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.
Member types iterator and const_iterator are bidirectional iterator types that point to elements.
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>
int main ()
{
std::list<int> mylist1, mylist2;
std::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();
std::advance(it,3); // "it" points now to 30
mylist1.splice ( mylist1.begin(), mylist1, it, mylist1.end());
// mylist1: 30 3 4 1 10 20
std::cout << "mylist1 contains:";
for (it=mylist1.begin(); it!=mylist1.end(); ++it)
std::cout << ' ' << *it;
std::cout << '\n';
std::cout << "mylist2 contains:";
for (it=mylist2.begin(); it!=mylist2.end(); ++it)
std::cout << ' ' << *it;
std::cout << '\n';
return 0;
}
| |
Output:
mylist1 contains: 30 3 4 1 10 20
mylist2 contains: 2
|
Complexity
Constant for (1) and (2).
Up to linear in the number of elements transferred for (3).
Iterator validity
No changes on the iterators, pointers and references related to the container before the call.
The iterators, pointers and references that referred to transferred elements keep referring to those same elements, but iterators now iterate into the container the elements have been transferred to.
Data races
Both the container and x are modified.
Concurrently accessing or modifying their elements is safe, although iterating x or ranges that include position is not.
Exception safety
If the allocators in both containers do not compare equal, if any of the iterators or ranges specified is not valid, or if x is *this in (1), or if position is in the range [first,last) in (3), it causes undefined behavior.
Otherwise, the function never throws exceptions (no-throw guarantee).