# std::list<T,Allocator>::splice

> C++ Atlas: `cppatlas.com/w/cpp/container/list/splice` | Source: https://en.cppreference.com/w/cpp/container/list/splice | Domain: Containers | Standards: C++11

Transfers elements from one list to another.

## Official Specification Summary (cppreference)

```cpp
void splice( const_iterator pos, list& other ); // (1)

void splice( const_iterator pos, list&& other ); // (2) (since C++11)

void splice( const_iterator pos, list& other, const_iterator it ); // (3)

void splice( const_iterator pos, list&& other, const_iterator it ); // (4) (since C++11)

void splice( const_iterator pos, list& other,
             const_iterator first, const_iterator last); // (5)

void splice( const_iterator pos, list&& other,
             const_iterator first, const_iterator last ); // (6) (since C++11)
```

Transfers elements from one list to another.

No elements are copied or moved, only the internal pointers of the list nodes are re-pointed. No iterators or references become invalidated, the iterators to moved elements remain valid, but now refer into `*this`, not into `other`.

1,2) Transfers all elements from `other` into `*this`. The elements are inserted before the element pointed to by `pos`. The container `other` becomes empty after the operation.

3,4) Transfers the element pointed to by `it` from `other` into `*this`. The element is inserted before the element pointed to by `pos`.

5,6) Transfers the elements in the range `[first,` `last)` from `other` into `*this`. The elements are inserted before the element pointed to by `pos`.

The behavior is undefined if

- `get_allocator() != other.get_allocator()`,
- for overloads (1,2), `*this` and `other` refer to the same object,
- for overloads (3,4), `it` is not a dereferenceable iterator into `other`, or
- for overloads (5,6),

  - `[first,` `last)` is not a valid range in `other`, or
  - `pos` is in `[first,` `last)`.

### 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`
- `first, last` - the range of elements to transfer from `other` to `*this`

### Return value

(none)

### Exceptions

Throws nothing.

### Complexity

1-4) Constant.

5,6) Constant if `other` refers to the same object as `*this`, otherwise linear in `std::distance(first, last)`.

### Example

```cpp
#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:

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

### 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 |

### See also

- [`merge`](https://en.cppreference.com/w/cpp/container/list/merge): merges two sorted lists (public member function)
- [`remove`](https://en.cppreference.com/w/cpp/container/list/remove), [`remove_if`](https://en.cppreference.com/w/cpp/container/list/remove): removes elements satisfying specific criteria (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/container/list/splice (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.