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

NAME
     std::regex_replace - std::regex_replace

Synopsis
	Defined in header <regex>
	template< class OutputIt, class BidirIt,

		  class Traits, class CharT,
		  class STraits, class SAlloc >
	OutputIt regex_replace( OutputIt out, BidirIt first, BidirIt last,
				const  std::basic_regex<CharT,Traits>&	re,  (1)
     (since C++11)
				const
	std::basic_string<CharT,STraits,SAlloc>& fmt,
				std::regex_constants::match_flag_type
	flags =

				    std::regex_constants::match_default );
	template< class OutputIt, class BidirIt,

		  class Traits, class CharT >
	OutputIt regex_replace( OutputIt out, BidirIt first, BidirIt last,
				const std::basic_regex<CharT,Traits>&  re,   (2)
     (since C++11)
				const CharT* fmt,
				std::regex_constants::match_flag_type
	flags =

				    std::regex_constants::match_default );
	template< class Traits, class CharT,

		  class STraits, class SAlloc,
		  class FTraits, class FAlloc >
	std::basic_string<CharT,STraits,SAlloc>
	    regex_replace( const std::basic_string<CharT,STraits,SAlloc>&
	s,								     (3)
     (since C++11)
			   const std::basic_regex<CharT,Traits>& re,
			   const std::basic_string<CharT,FTraits,FAlloc>&
	fmt,
			   std::regex_constants::match_flag_type flags =

			       std::regex_constants::match_default );
	template< class Traits, class CharT,

		  class STraits, class SAlloc >
	std::basic_string<CharT,STraits,SAlloc>
	    regex_replace( const std::basic_string<CharT,STraits,SAlloc>&
	s,								     (4)
     (since C++11)
			   const std::basic_regex<CharT,Traits>& re,
			   const CharT* fmt,
			   std::regex_constants::match_flag_type flags =

			       std::regex_constants::match_default );
	template< class Traits, class CharT,

		  class STraits, class SAlloc >
	std::basic_string<CharT>
	    regex_replace( const CharT* s,
			   const  std::basic_regex<CharT,Traits>&  re,	     (5)
     (since C++11)
			   const std::basic_string<CharT,STraits,SAlloc>&
	fmt,
			   std::regex_constants::match_flag_type flags =

			       std::regex_constants::match_default );
	template< class Traits, class CharT >

	std::basic_string<CharT>
	    regex_replace( const CharT* s,
			   const std::basic_regex<CharT,Traits>&  re,	     (6)
     (since C++11)
			   const CharT* fmt,
			   std::regex_constants::match_flag_type flags =

			       std::regex_constants::match_default );

	regex_replace uses a regular expression to perform substitution on a se-
     quence of
	characters:

	1)  Copies  characters	in the range [first, last) to out, replacing any
     sequences that
	match re with characters formatted by fmt. In other words:

	  * Constructs a std::regex_iterator object i as if by std::regex_itera-
     tor<BidirIt,
	    CharT, traits> i(first, last,  re,	flags),  and  uses  it	to  step
     through every
	    match of re within the sequence [first, last).
	  *  For  each	such match m, copies the non-matched subsequence (m.pre-
     fix()) into out
	    as if by out = std::copy(m.prefix().first,	m.prefix().second,  out)
     and then
	    replaces  the  matched  subsequence  with  the formatted replacement
     string as if by
	    calling out = m.format(out, fmt, flags).
	  * When no more matches are found,  copies  the  remaining  non-matched
     characters to
	    out  as  if  by  out  = std::copy(last_m.suffix().first, last_m.suf-
     fix().second, out)
	    where last_m is a copy of the last match found.
	  * If there are no matches, copies the entire sequence into out  as-is,
     by out =
	    std::copy(first, last, out).
	  *  If  flags	contains  std::regex_constants::format_no_copy, the non-
     matched
	    subsequences are not copied into out.
	  * If flags contains std::regex_constants::format_first_only, only  the
     first match
	    is replaced.
	2)  Same  as  (1),  but  the formatted replacement is performed as if by
     calling out =
	m.format(out, fmt, fmt + char_traits<CharT>::length(fmt), flags).
	3,4) Constructs an empty string result of type	std::basic_string<CharT,
     ST, SA> and
	calls std::regex_replace(std::back_inserter(result), s.begin(), s.end(),
     re, fmt,
	flags).
	5,6)  Constructs an empty string result of type std::basic_string<CharT>
     and calls
	std::regex_replace(std::back_inserter(result), s, s +
	std::char_traits<CharT>::length(s), re, fmt, flags).

Parameters
	first, last - the input character sequence, represented as a pair of it-
     erators
	s	    - the input  character  sequence,  represented  as	std::ba-
     sic_string or
		      character array
	re	     - the std::basic_regex that will be matched against the in-
     put sequence
	fmt	    - the regex replacement format string, exact syntax  depends
     on the value
		      of flags
	flags	       -    the    match    flags    of   type	 std::regex_con-
     stants::match_flag_type
	out	    - output iterator to store the result of the replacement

Type requirements
	-
	OutputIt must meet the requirements of LegacyOutputIterator.
	-
	BidirIt must meet the requirements of LegacyBidirectionalIterator.

Return value
	1,2) Returns a copy of the output iterator out after all the insertions.
	3-6) Returns the string result which contains the output.

Exceptions
	May throw std::regex_error to indicate an error condition.

Example
     // Run this code

      #include <iostream>
      #include <iterator>
      #include <regex>
      #include <string>

      int main()
      {
	 std::string text = "Quick brown fox";
	 std::regex vowel_re("a|e|i|o|u");

	 // write the results to an output iterator
	 std::regex_replace(std::ostreambuf_iterator<char>(std::cout),
			    text.begin(), text.end(), vowel_re, "*");

	 // construct a string holding the results
	 std::cout << '\n'  <<	std::regex_replace(text,  vowel_re,  "[$&]")  <<
     '\n';
      }

Output:
      Q**ck br*wn f*x
      Q[u][i]ck br[o]wn f[o]x

See also
	regex_search	 attempts to match a regular expression to any part of a
     character
	(C++11) 	sequence
			(function template)
	match_flag_type options specific to matching
	(C++11) 	(typedef)
			replaces specified portion of a string
	replace 	(public member function of
			std::basic_string<CharT,Traits,Allocator>)

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