< cpp‎ | container‎ | deque
template< container-compatible-range<T> R >
iterator insert_range( const_iterator pos, R&& rg );
(since C++23)

Inserts, in non-reversing order, copies of elements in rg before pos.

All iterators (including the end() iterator) are invalidated. References are invalidated too, unless pos == begin() or pos == end(), in which case they are not invalidated.

Each iterator in the range rg is dereferenced exactly once.

The behavior is undefined if rg overlaps with the container.


[edit] Parameters

pos - iterator before which the content will be inserted (pos may be the end() iterator)
rg - a container compatible range, that is, an input_range whose elements are convertible to T
Type requirements
T must be EmplaceConstructible into deque from *ranges::begin(rg). Also, T must be MoveInsertable into deque and T satisfies MoveConstructible, MoveAssignable, and Swappable. Otherwise, the behavior is undefined.

[edit] Return value

An iterator that points at the copy of the first element inserted into deque or at pos if rg is empty.

[edit] Notes

Feature-test macro Value Std Feature
__cpp_lib_containers_ranges 202202L (C++23) Ranges-aware construction and insertion

[edit] Example

#include <algorithm>
#include <cassert>
#include <iterator>
#include <deque>
#include <list>
int main()
    auto container = std::deque{1, 2, 3, 4};
    auto pos = std::next(container.begin(), 2);
    assert(*pos == 3);
    const auto rg = std::list{-1, -2, -3};
#ifdef __cpp_lib_containers_ranges
    container.insert_range(pos, rg);
    container.insert(pos, rg.cbegin(), rg.cend());
    assert(std::ranges::equal(container, std::deque{1, 2, -1, -2, -3, 3, 4}));

[edit] See also

inserts elements
(public member function)
adds a range of elements to the beginning
(public member function)
adds a range of elements to the end
(public member function)