| Home | Libraries | People | FAQ | More

### Matching and Searching

### 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 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
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.