# 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 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 | Comment
--- | --- | --- | ---
`__cpp_lib_containers_ranges` | 202202L | (C++23) | member functions that accept container compatible range

### Example

| This section is incomplete Reason: no example

### 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=155506"