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
| inserts characters (public member function) |