std::basic_string<CharT,Traits,Allocator>::insert_range
From cppreference.com
< cpp | string | basic string
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
std::basic_string
Literals Helper classes Deduction guides (C++17)
(C++23)
(DR*)
(DR*)
basic_string::insert_range
(C++23)
(DR*)
(C++23)
(C++23)
(C++20)
(C++20)
(C++23)
(C++20)(C++20)
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++14)
(C++11)
template< container-compatible-range <CharT> R >
constexpr iterator insert_range( const_iterator pos, R&& rg );
(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.
[edit] Parameters
pos
-
iterator before which the characters will be inserted
rg
-
a container compatible range
[edit] Return value
An iterator which refers to the first inserted character, or pos if no characters were inserted because rg was empty.
[edit] Complexity
Linear in size of rg.
[edit] 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).
[edit] Notes
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_containers_ranges |
202202L |
(C++23) | member functions that accept container compatible range |
[edit] 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"); // ^^^^ }