std::list<T,Allocator>::splice
From cppreference.com
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Containers library
(C++17)
(C++11)
(C++26)
(C++26)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20)
(C++23)
Tables
std::list
Non-member functions
Deduction guides (C++17)
(C++23)
(C++11)
(C++11)
(C++11)
(C++11)
(C++23)
(C++11)
(C++11)
(C++23)
(C++11)
(C++23)
list::splice
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)
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)
const_iterator first, const_iterator last );
void splice( const_iterator pos, list&& other,
const_iterator first, const_iterator last );
(6)
(since C++11) const_iterator first, const_iterator last );
(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.
[edit] 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
[edit] Complexity
1-4) Constant.
5,6) Constant if other refers to the same object as *this, otherwise linear in std::distance (first, last).
[edit] 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
[edit] 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 |