std::basic_string::insert_range(3)

NAME
std::basic_string::insert_range - std::basic_string::insert_range

Synopsis
   template< container-compatible-range<CharT> R > (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.

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 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)