source: downloads/boost_1_34_1/libs/xpressive/doc/matching.qbk @ 29

[section Matching and Searching]

[h2 Overview]

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 _regexpp_ library work, xpressive's versions work the same way.

[h2 Seeing if a String Matches a Regex]

The _regex_match_ algorithm checks to see if a regex matches a given input.

[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 `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 [link boost_xpressive.user_s_guide.quick_start.know_your_iterator_type 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 [link boost_xpressive.user_s_guide.examples.see_if_a_whole_string_matches_a_regex 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.

[h2 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 `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 [link boost_xpressive.user_s_guide.examples.see_if_a_string_contains_a_sub_string_that_matches_a_regex 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.

[endsect]