home | help 
std::basic_...insert_range(3)  C++ Standard Libary std::basic_...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)

http://cppreference.com 	   2024.06.10	   std::basic_...insert_range(3)
home | help