public member function
<forward_list>
| entire list (1) | void splice_after (const_iterator position, forward_list& fwdlst);void splice_after (const_iterator position, forward_list&& fwdlst); |
|---|
| single element (2) | void splice_after (const_iterator position, forward_list& fwdlst, const_iterator i);void splice_after (const_iterator position, forward_list&& fwdlst, const_iterator i); |
|---|
| element range (3) | void splice_after (const_iterator position, forward_list& fwdlst, const_iterator first, const_iterator last);void splice_after (const_iterator position, forward_list&& fwdlst, const_iterator first, const_iterator last); |
|---|
Transfer elements from another forward_list
Transfers elements from fwdlst into the container inserting them after the element pointed by position.
This effectively inserts those elements into the container and removes them from fwdlst, altering the sizes of both containers. The operation does not involve the construction or destruction of any element. They are transferred, no matter whether fwdlst 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 fwdlst into the container.
The second version (2) transfers only the element pointed by i from fwdlst into the container.
The third version (3) transfers the range (first,last) from fwdlst into the container.
Parameters
- position
- Position within the container after which the elements of fwdlst are inserted.
Member type const_iterator is a forward iterator that points to const elements.
- fwdlst
- A forward_list object of the same type (i.e., with the same template parameters, T and Alloc) and using an identical allocator.
This parameter may be *this if position points to an element not actually being spliced: for the two-parameters version (1), this is never the case, but for the other versions this is possible.
Note that this function modifies fwdlst, removing elements from it, no matter whether an lvalue or rvalue reference is passed.
- i
- Iterator to an element in fwdlst preceding the one to be transferred. Only the single element that follows this is transferred.
Member type const_iterator is a forward iterator that points to const elements.
- first,last
- Iterators specifying an open interval range of elements in fwdlst. The function transfers the elements in the range (first,last) to position.
Notice that, in this function, the range is open and includes all the elements between first and last, but not first nor last themselves.
Member type const_iterator is a forward iterator that points to const 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
|
// forward_list::splice_after
#include <iostream>
#include <forward_list>
int main ()
{
std::forward_list<int> first = { 1, 2, 3 };
std::forward_list<int> second = { 10, 20, 30 };
auto it = first.begin(); // points to the 1
first.splice_after ( first.before_begin(), second );
// first: 10 20 30 1 2 3
// second: (empty)
// "it" still points to the 1 (now first's 4th element)
second.splice_after ( second.before_begin(), first, first.begin(), it);
// first: 10 1 2 3
// second: 20 30
first.splice_after ( first.before_begin(), second, second.begin() );
// first: 30 10 1 2 3
// second: 20
// * notice that what is moved is AFTER the iterator
std::cout << "first contains:";
for (int& x: first) std::cout << " " << x;
std::cout << std::endl;
std::cout << "second contains:";
for (int& x: second) std::cout << " " << x;
std::cout << std::endl;
return 0;
}
|
first contains: 30 10 1 2 3
second contains: 20
|
Complexity
Up to linear in the number of elements transferred.
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 fwdlst 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).