Boost C++ Libraries Home Libraries People FAQ More


Matching and Searching


Once you have created a regex object, you can use the regex_match() and regex_search() algorithms to find patterns in strings. This page covers the basics of regex matching and searching. In all cases, if you are familiar with how regex_match() and regex_search() in the Boost.Regex library work, xpressive's versions work the same way.

Seeing if a String Matches a Regex

The regex_match() algorithm checks to see if a regex matches a given input.

[Warning] Warning

The regex_match() algorithm will only report success if the regex matches the whole input, from beginning to end. If the regex matches only a part of the input, regex_match() will return false. If you want to search through the string looking for sub-strings that the regex matches, use the regex_search() algorithm.

The input can be a bidirectional range such as std::string, a C-style null-terminated string or a pair of iterators. In all cases, the type of the iterator used to traverse the input sequence must match the iterator type used to declare the regex object. (You can use the table in the Quick Start to find the correct regex type for your iterator.)

cregex cre = +_w;  // this regex can match C-style strings
sregex sre = +_w;  // this regex can match std::strings

if( regex_match( "hello", cre ) )              // OK
    { /*...*/ }

if( regex_match( std::string("hello"), sre ) ) // OK
    { /*...*/ }

if( regex_match( "hello", sre ) )              // ERROR! iterator mis-match!
    { /*...*/ }

The regex_match() algorithm optionally accepts a match_results<> struct as an out parameter. If given, the regex_match() algorithm fills in the match_results<> struct with information about which parts of the regex matched which parts of the input.

cmatch what;
cregex cre = +(s1= _w);

// store the results of the regex_match in "what"
if( regex_match( "hello", what, cre ) )
    std::cout << what[1] << '\n'; // prints "o"

The regex_match() algorithm also optionally accepts a match_flag_type bitmask. With match_flag_type, you can control certain aspects of how the match is evaluated. See the match_flag_type reference for a complete list of the flags and their meanings.

std::string str("hello");
sregex sre = bol >> +_w;

// match_not_bol means that "bol" should not match at [begin,begin)
if( regex_match( str.begin(), str.end(), sre, regex_constants::match_not_bol ) )
    // should never get here!!!

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

Searching for Matching Sub-Strings

Use regex_search() when you want to know if an input sequence contains a sub-sequence that a regex matches. regex_search() will try to match the regex at the beginning of the input sequence and scan forward in the sequence until it either finds a match or exhausts the sequence.

In all other regards, regex_search() behaves like regex_match() (see above). In particular, it can operate on a bidirectional range such as std::string, C-style null-terminated strings or iterator ranges. The same care must be taken to ensure that the iterator type of your regex matches the iterator type of your input sequence. As with regex_match(), you can optionally provide a match_results<> struct to receive the results of the search, and a match_flag_type bitmask to control how the match is evaluated.

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