| Home | Libraries | People | FAQ | More

### Accessing Results

### Overview

Sometimes, it is not enough to know simply whether a ``regex_match()`` or ``regex_search()`` was successful or not. If you pass an object of type ``match_results<>`` to ``regex_match()`` or ``regex_search()``, then after the algorithm has completed successfully the ``match_results<>`` will contain extra information about which parts of the regex matched which parts of the sequence. In Perl, these sub-sequences are called back-references, and they are stored in the variables `$1`, `$2`, etc. In xpressive, they are objects of type ``sub_match<>``, and they are stored in the ``match_results<>`` structure, which acts as a vector of ``sub_match<>`` objects.

### match_results

So, you've passed a ``match_results<>`` object to a regex algorithm, and the algorithm has succeeded. Now you want to examine the results. Most of what you'll be doing with the ``match_results<>`` object is indexing into it to access its internally stored ``sub_match<>`` objects, but there are a few other things you can do with a ``match_results<>`` object besides.

The table below shows how to access the information stored in a ``match_results<>`` object named `what`.

Table 1.5. match_results<> Accessors

Accessor | Effects
--- | ---
`what.size()` | Returns the number of sub-matches, which is always greater than zero after a successful match because the full match is stored in the zero-th sub-match.
`what[n]` | Returns the n-th sub-match.
`what.length(n)` | Returns the length of the n-th sub-match. Same as `what[n].length()`.
`what.position(n)` | Returns the offset into the input sequence at which the n-th sub-match begins.
`what.str(n)` | Returns a `std::basic_string<>` constructed from the n-th sub-match. Same as `what[n].str()`.
`what.prefix()` | Returns a ``sub_match<>`` object which represents the sub-sequence from the beginning of the input sequence to the start of the full match.
`what.suffix()` | Returns a ``sub_match<>`` object which represents the sub-sequence from the end of the full match to the end of the input sequence.
`what.regex_id()` | Returns the `regex_id` of the ``basic_regex<>`` object that was last used with this ``match_results<>`` object.

There is more you can do with the ``match_results<>`` object, but that will be covered when we talk about Grammars and Nested Matches.

### sub_match

When you index into a ``match_results<>`` object, you get back a ``sub_match<>`` object. A ``sub_match<>`` is basically a pair of iterators. It is defined like this:

    template< class BidirectionalIterator >
    struct sub_match
        : std::pair< BidirectionalIterator, BidirectionalIterator >
    {
        bool matched;
        // ...
    };

Since it inherits publicaly from `std::pair<>`, ``sub_match<>`` has `first` and `second` data members of type `BidirectionalIterator`. These are the beginning and end of the sub-sequence this ``sub_match<>`` represents. ``sub_match<>`` also has a Boolean `matched` data member, which is true if this ``sub_match<>`` participated in the full match.

The following table shows how you might access the information stored in a ``sub_match<>`` object called `sub`.

Table 1.6. sub_match<> Accessors

Accessor | Effects
--- | ---
`sub.length()` | Returns the length of the sub-match. Same as `std::distance(sub.first,sub.second)`.
`sub.str()` | Returns a `std::basic_string<>` constructed from the sub-match. Same as `std::basic_string<char_type>(sub.first,sub.second)`.
`sub.compare(str)` | Performs a string comparison between the sub-match and `str`, where `str` can be a `std::basic_string<>`, C-style null-terminated string, or another sub-match. Same as `sub.str().compare(str)`.

### Results Invalidation

Results are stored as iterators into the input sequence. Anything which invalidates the input sequence will invalidate the match results. For instance, if you match a `std::string` object, the results are only valid until your next call to a non-const member function of that `std::string` object. After that, the results held by the ``match_results<>`` object are invalid. Don't use them!