Skip to content

Search topics & cppreference

Search all study topics, concept maps, and 6,587 C++ and C reference pages.

std::basic_string<CharT,Traits,Allocator>::insert_range

Inserts characters from the range rg before the element (if any) pointed by pos.

NotebookLM
template< container-compatible-range<CharT> R >
constexpr iterator insert_range( const_iterator pos, R&& rg );
(since C++23)

Inserts characters from the range rg before the element (if any) pointed by pos.

Equivalent to

snippet.cpp
return insert(pos - begin(),
    std::basic_string(
        std::from_range,
        std​::​forward<R>(rg),
        get_allocator())
);

If pos is not a valid iterator on *this, the behavior is undefined.

Parameters

pos - iterator before which the characters will be inserted
rg - a container compatible range

Return value

An iterator which refers to the first inserted character, or pos if no characters were inserted because rg was empty.

Complexity

Linear in size of rg.

Exceptions

If std::allocator_traits<Allocator>::allocate throws an exception, it is rethrown.

If the operation would cause size() to exceed max_size(), throws std::length_error.

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).

Notes

Feature-test macro Value Std Feature
__cpp_lib_containers_ranges 202202L (C++23) member functions that accept container compatible range

Example

example.cpp
#include <cassert>
#include <iterator>
#include <string>
 
int main()
{
    const auto source = {'l', 'i', 'b', '_'};
    std::string target{"__cpp_containers_ranges"};
    //                        ^insertion will occur
    //                         before this position
 
    const auto pos = target.find("container");
    assert(pos != target.npos);
    auto iter = std::next(target.begin(), pos);
 
#ifdef __cpp_lib_containers_ranges
    target.insert_range(iter, source);
#else
    target.insert(iter, source.begin(), source.end());
#endif
 
    assert(target == "__cpp_lib_containers_ranges");
    //                      ^^^^
}

See also

inserts characters
(public member function)

Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.