boost_1_45_0/libs/xpressive/doc/matching.qbk

[/
 / Copyright (c) 2008 Eric Niebler
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[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 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
[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 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 [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]