NAME¶

std::basic_string::insert_range - std::basic_string::insert_range

Synopsis¶

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

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

Equivalent to

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 result in size() > 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¶

// Run this code

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

insert inserts characters
(public member function)