std::regex_replace(3)

💅 std::regex_replace — the C++ Standard Library glow-up you've been waiting for

okay bestie, so this one lives in the C++ Standard Library and it's literally the find-and-replace of your regex dreams. std::regex_replace is the name, replacing matching stuff is the game, and she's been here since C++11. periodt. ✨

---

🌸 SYNOPSIS 🌸

First things first, she's Defined in header <regex> 🎀

Overload (1) — (since C++11)

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,
                        const std::basic_string<CharT,STraits,SAlloc>& fmt,
                        std::regex_constants::match_flag_type flags =
                            std::regex_constants::match_default );

Overload (2) — (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>& re,
                        const CharT* fmt,
                        std::regex_constants::match_flag_type flags =
                            std::regex_constants::match_default );

Overload (3) — (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>& re,
                   const std::basic_string<CharT,FTraits,FAlloc>& fmt,
                   std::regex_constants::match_flag_type flags =
                       std::regex_constants::match_default );

Overload (4) — (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>& re,
                   const CharT* fmt,
                   std::regex_constants::match_flag_type flags =
                       std::regex_constants::match_default );

Overload (5) — (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>& re,
                   const std::basic_string<CharT,STraits,SAlloc>& fmt,
                   std::regex_constants::match_flag_type flags =
                       std::regex_constants::match_default );

Overload (6) — (since C++11)

template< class Traits, class CharT >
std::basic_string<CharT>
    regex_replace( const CharT* s,
                   const std::basic_regex<CharT,Traits>& re,
                   const CharT* fmt,
                   std::regex_constants::match_flag_type flags =
                       std::regex_constants::match_default );

---

💖 DESCRIPTION 💖

so regex_replace uses a regular expression to perform substitution on a sequence of characters, and honestly? it's giving main character energy. here's the whole breakdown:

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_iterator<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.prefix()) 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.suffix().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. 🫶 (she's selective, we respect it)
• If flags contains std::regex_constants::format_first_only, only the first match is replaced. one and done, iconic.

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 iterators
• s — the input character sequence, represented as std::basic_string or character array
• re — the std::basic_regex that will be matched against the input sequence
• fmt — the regex replacement format string, exact syntax depends on the value of flags (iykyk, check the flags bestie)
• flags — the match flags of type std::regex_constants::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.

no cap, those are non-negotiable 💅

---

🎀 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. 😭 (she's dramatic but fair)

---

🌈 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

look at her go. vowels got absolutely ate. ⭐

---

👑 SEE ALSO 👑

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

---

and that's the whole page, bestie 💜 huge thanks to cppreference.com, version 2024.06.10 — this little love letter to std::regex_replace was dated then too, so go forth and replace responsibly 🧚‍♀️✨