Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

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


caution Results Invalidation caution

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!


PrevUpHomeNext