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

From cppreference.com
< cpp‎ | string‎ | basic string

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

    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

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)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/insert_range&oldid=161646"