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

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

Вставляет символы из диапазона rg перед элементом (если он есть), на который указывает pos.

Эквивалентно

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

Если pos не является допустимым итератором для *this, поведение не определено.

Параметры

Возвращаемое значение

Итератор, указывающий на первый вставленный символ, или pos, если символы не были вставлены, поскольку rg был пуст.

Сложность

Линейная относительно размера rg.

Исключения

Если std::allocator_traits<Allocator>::allocate выбрасывает исключение, оно повторно выбрасывается.

Если операция приведёт к тому, что size() превысит max_size(), выбрасывается std::length_error.

Если по какой-либо причине выбрасывается исключение, эта функция не оказывает никакого эффекта (гарантия строгой безопасности при исключениях).

Примечания

Пример

#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");
    //                      ^^^^
}

См. также