std::regex_replace

 

C++

Language

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Regular expressions library

Classes

basic_regex (C++11)

sub_match (C++11)

match_results (C++11)

Algorithms

regex_match (C++11)

regex_search (C++11)

regex_replace (C++11)

Iterators

regex_iterator (C++11)

regex_token_iterator (C++11)

Exceptions

regex_error (C++11)

Traits

regex_traits (C++11)

Constants

syntax_option_type (C++11)

match_flag_type (C++11)

error_type (C++11)

 

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>& e,                         const std::basic_string<CharT,STraits,SAlloc>& fmt,                         std::regex_constants::match_flag_type flags =                             std::regex_constants::match_default );	(1)	(since C++11)
template< class OutputIt, class BidirIt,           class Traits, class CharT > OutputIt regex_replace( OutputIt out, BidirIt first, BidirIt last,                         const std::basic_regex<CharT,Traits>& e,                         const CharT* fmt,                         std::regex_constants::match_flag_type flags =                             std::regex_constants::match_default );	(2)	(since C++11)
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,                    const std::basic_regex<CharT,Traits>& e,                    const std::basic_string<CharT,FTraits,FAlloc>& fmt,                    std::regex_constants::match_flag_type flags =                        std::regex_constants::match_default );	(3)	(since C++11)
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,                    const std::basic_regex<CharT,Traits>& e,                    const CharT* fmt,                    std::regex_constants::match_flag_type flags =                        std::regex_constants::match_default );	(4)	(since C++11)
template< class Traits, class CharT,           class STraits, class SAlloc > std::basic_string<CharT>     regex_replace( const CharT* s,                    const std::basic_regex<CharT,Traits>& e,                    const std::basic_string<CharT,STraits,SAlloc>& fmt,                    std::regex_constants::match_flag_type flags =                        std::regex_constants::match_default );	(5)	(since C++11)
template< class Traits, class CharT > std::basic_string<CharT>     regex_replace( const CharT* s,                    const std::basic_regex<CharT,Traits>& e,                    const CharT* fmt,                    std::regex_constants::match_flag_type flags =                        std::regex_constants::match_default );	(6)	(since C++11)

1) Constructs a std::regex_iterator object i as if by std::regex_iterator<BidirIt, CharT, traits> i(first, last, e, flags), and uses it to step through every match of e within the sequence [first,last). For each such match m, copies the non-matched subsequence (m.prefix()) into out as-is and then replaces the matched subsequence with the formatted replacement string as if by calling m.format(out, fmt, flags). When no more matches are found, copies the remaining non-matched characters to out.

If there are no matches, copies the entire sequence into out as-is.

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 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(), e, 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), e, fmt, flags).

Parameters

first, last	-	the input character sequence, represented as a pair of iterators
s	-	the input character sequence, represented as std::basic_string or character array
e	-	the std::basic_regex that will be matched against the input sequence
flags	-	the match flags of type std::regex_constants::match_flag_type
fmt	-	the regex replacement format string, exact syntax depends on the value of flags
out	-	output iterator to store the result of the replacement
Type requirements
- OutputIt must meet the requirements of OutputIterator.
- BidirIt must meet the requirements of BidirectionalIterator.

Return value

1-2) Returns a copy of the output iterator out.

3-6) Returns the string result which contains the output.

Exceptions

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

Example

#include <iostream>
#include <regex>
#include <string>
int main()
{
   std::string text = "Quick brown fox";
   std::regex vowel_re("a|o|e|u|i");
   std::cout << std::regex_replace(text, vowel_re, "[$&]") << '\n';
}

Output:

Q[u][i]ck br[o]wn f[o]x

See also

regex_search (C++11)	attempts to match a regular expression to any part of the character sequence (function template)
match_flag_type (C++11)	options specific to matching (typedef)