Regular expressions are not only good for searching text; they're good at manipulating it. And one of the most common text manipulation tasks is search-and-replace. xpressive provides the regex_replace() algorithm for searching and replacing.

regex_replace()

Performing search-and-replace using regex_replace() is simple. All you need is an input sequence, a regex object, and a format string. There are two versions of the regex_replace() algorithm. The first accepts the input sequence as std::basic_string<> and returns the result in a new std::basic_string<>. The second accepts the input sequence as a pair of iterators, and writes the result into an output iterator. Below are examples of each.

std::string input("This is his face");
sregex re = as_xpr("his");                // find all occurrences of "his" ...
std::string format("her");                // ... and replace them with "her"

// use the version of regex_replace() that operates on strings
std::string output = regex_replace( input, re, format );
std::cout << output << '\n';

// use the version of regex_replace() that operates on iterators
std::ostream_iterator< char > out_iter( std::cout );
regex_replace( out_iter, input.begin(), input.end(), re, format );

The above program prints out the following:

Ther is her face
Ther is her face

Notice that all the occurrences of "his" have been replaced with "her".

Click here to see a complete example program that shows how to use regex_replace(). And check the regex_replace() reference to see a complete list of the available overloads.

The Format String

As with Perl, you can refer to sub-matches in the format string. The table below shows the escape sequences xpressive recognizes in the format string.

Any other sequence beginning with '$' simply represents itself. For example, if the format string were "$a" then "$a" would be inserted into the output sequence.

Replace Options

The regex_replace() algorithm takes an optional bitmask parameter to control the formatting. The possible values of the bitmask are:

These flags live in the regex_constants namespace.