Difference between revisions of "cpp/string/basic string/insert range"
From cppreference.com
< cpp | string | basic string
m (→Notes: +FTM; fmt.) |
m (→Example: +comment) |
||
| (4 intermediate revisions by one user not shown) | |||
| Line 23: | Line 23: | ||
{{par begin}} | {{par begin}} | ||
{{par|pos|iterator before which the characters will be inserted}} | {{par|pos|iterator before which the characters will be inserted}} | ||
| − | {{par|rg|a | + | {{par|rg|a {{ls|cpp/ranges/to#container compatible range}}}} |
{{par end}} | {{par end}} | ||
| Line 33: | Line 33: | ||
===Exceptions=== | ===Exceptions=== | ||
| − | |||
| − | |||
If {{c/core|std::allocator_traits<Allocator>::allocate}} throws an exception, it is rethrown. | If {{c/core|std::allocator_traits<Allocator>::allocate}} throws an exception, it is rethrown. | ||
| + | |||
| + | {{cpp/string/basic_string/length error note}} | ||
{{cpp/strong exception safety guarantee}} | {{cpp/strong exception safety guarantee}} | ||
===Notes=== | ===Notes=== | ||
| − | {{feature test macro|__cpp_lib_containers_ranges|value=202202L|std=C++23|member functions that accept | + | {{feature test macro|__cpp_lib_containers_ranges|value=202202L|std=C++23|member functions that accept {{ls|cpp/ranges/to#container compatible range}}}} |
===Example=== | ===Example=== | ||
| − | {{example}} | + | {{example |
| + | |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=== | ===See also=== | ||
Latest revision as of 14:35, 28 October 2023
| 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.
Contents |
[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 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).
[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"); // ^^^^ }
[edit] See also
| inserts characters (public member function) |
