home | help 
std::basic_string::replace(3)  C++ Standard Libary std::basic_string::replace(3)

NAME
     std::basic_string::replace - std::basic_string::replace

Synopsis
	basic_string& replace( size_type pos,
	size_type count,			       (1) (constexpr since
			       const basic_string& str	   C++20)
	);
	basic_string& replace( const_iterator first,
	const_iterator last,			       (2) (constexpr since
			       const basic_string& str	   C++20)
	);
	basic_string& replace( size_type pos,
	size_type count,

			       const basic_string&			    (un-
     til C++14)
	str,

			       size_type pos2,
	size_type count2 );
	basic_string& replace( size_type pos,
	size_type count,
									    (since
     C++14)
			       const				   basic_string&
     (constexpr since
	str,
     C++20)

			       size_type pos2,
	size_type count2 = npos );
	basic_string& replace( size_type pos,
	size_type	   count,					     (4)
     (constexpr since
			       const		     CharT*		   cstr,
     C++20)
	size_type count2 );
	basic_string& replace( const_iterator first,
	const_iterator		last,					     (5)
     (constexpr since
			       const		     CharT*		   cstr,
     C++20)
	size_type count2 );
	basic_string&		 replace(	      size_type 	    pos,
     (constexpr since
	size_type	   count,					     (6)
     C++20)
			       const CharT* cstr );
	basic_string&	       replace( 	 const_iterator 	  first,
     (constexpr since
	const_iterator		last,					     (7)
     C++20)
			       const CharT* cstr );
	basic_string& replace( size_type pos,
	size_type	   count,					     (8)
     (constexpr since
			       size_type	      count2,		   CharT
     C++20)
	ch );
	basic_string& replace( const_iterator first,
	const_iterator	     last,				   (3)	     (9)
     (constexpr since
			       size_type	      count2,		   CharT
     C++20)
	ch );
	template< class InputIt >

	basic_string&	       replace( 	 const_iterator 	  first,
     (constexpr since
	const_iterator		last,					    (10)
     C++20)

			       InputIt first2, InputIt
	last2 );
	basic_string&	       replace( 	 const_iterator 	  first,
     (since C++11)
	const_iterator		last,					    (11)
     (constexpr since
									    C++20)
	 std::initializer_list<CharT> ilist );
	template< class StringViewLike >

	basic_string&		 replace(	      size_type 	    pos,
     (since C++17)
	size_type	   count,					    (12)
     (constexpr since
									    C++20)
			       const StringViewLike& t
	);
	template< class StringViewLike >

	basic_string&	       replace( 	 const_iterator 	  first,
     (since C++17)
	const_iterator		last,					    (13)
     (constexpr since
									    C++20)
			       const StringViewLike& t
	);
	template< class StringViewLike >

	basic_string& replace( size_type pos,
	size_type							  count,
     (since C++17)
			       const	      StringViewLike&		    (14)
     (constexpr since
	t,
     C++20)

			       size_type pos2,
	size_type count2 = npos );

	Replaces  the  characters  in  the  range  [begin()  +	pos,  begin()  +
     std::min(pos + count,
	size())) or [first, last) with given characters.

	1,2) Those characters are replaced with str.
	3) Those characters are replaced with a substring [pos2, std::min(pos2 +
     count2,
	str.size())) of str.
	4,5)  Those  characters  are  replaced	with the characters in the range
     [cstr, cstr +
	count2).
	If [cstr, cstr + count2) is not a valid range,	the  behavior  is  unde-
     fined.
	6,7)  Those  characters  are  replaced	with the characters in the range
     [cstr, cstr +
	Traits::length(cstr)).
	8,9) Those characters are replaced with count2 copies of ch.
	10) Those characters are replaced  with  the  characters  in  the  range
     [first2, last2)
	as  if	by  replace(first, last, basic_string(first2, last2, get_alloca-
     tor())).
	11) Those characters are replaced with the characters in ilist.
	12,13) Implicitly converts t to a string view sv as if by
	std::basic_string_view<CharT, Traits> sv = t;, then those characters are
     replaced
	with the characters from sv.
	These overloads participate in overload resolution only if
	std::is_convertible_v<const StringViewLike&,
			      std::basic_string_view<CharT, Traits>> is true and
	std::is_convertible_v<const StringViewLike&, const CharT*> is false.
	14) Implicitly converts t  to  a  string  view	sv  as	if  by	std::ba-
     sic_string_view<CharT,
	Traits>  sv = t;, then those characters are replaced with the characters
     from the
	subview sv.substr(pos2, count2).
	This overload participates in overload resolution only if
	std::is_convertible_v<const StringViewLike&,
			      std::basic_string_view<CharT, Traits>> is true and
	std::is_convertible_v<const StringViewLike&, const CharT*> is false.

	If [begin(), first) or [first, last) is not a valid range, the	behavior
     is
	undefined.

Parameters
	pos	      - start of the substring that is going to be replaced
	count	      - length of the substring that is going to be replaced
	first, last   - range of characters that is going to be replaced
	str	      - string to use for replacement
	pos2	      - start of the substring to replace with
	count2	      - number of characters to replace with
	cstr	      - pointer to the character string to use for replacement
	ch	      - character value to use for replacement
	first2, last2 - range of characters to use for replacement
	ilist	      - initializer list with the characters to use for replace-
     ment
	t	       - object (convertible to std::basic_string_view) with the
     characters
			to use for replacement

Type requirements
	-
	InputIt must meet the requirements of LegacyInputIterator.

Return value
	*this.

Exceptions
	1) Throws std::out_of_range if pos > size().
	3) Throws std::out_of_range if pos > size() or pos2 > str.size().
	4,6,8) Throws std::out_of_range if pos > size().
	12,14) Throws std::out_of_range if pos > size().

	If  the  operation  would  result  in  size()	>   max_size(),   throws
     std::length_error.

	If an exception is thrown for any reason, these functions have no effect
     (strong
	exception safety guarantee).

Example
	 This section is incomplete
	 Reason: no example

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to	 Behavior as published		    Correct  be-
     havior
	LWG  847  C++98      there was no exception safety   added strong excep-
     tion safety
			    guarantee			    guarantee
	LWG 1323 C++98	    the types of first and last     changed to const_it-
     erator
			    were iterator
	LWG 2946 C++17	    overloads (12,13) caused	     avoided  by  making
     them templates
			    ambiguity in some cases

See also
	replace_with_range  replaces  specified portion of a string with a range
     of characters
	(C++23) 	   (public member function)
	regex_replace	   replaces occurrences of  a  regular	expression  with
     formatted
	(C++11) 	   replacement text
			   (function template)
	replace 	   replaces all values satisfying specific criteria with
     another
	replace_if	   value
			   (function template)

Category:
	  * Todo no example

http://cppreference.com 	   2024.06.10	   std::basic_string::replace(3)
home | help