sub_match Class

Describes a submatch.

Syntax

template <class BidIt>
class sub_match
    : public std::pair<BidIt, BidIt>

Parameters

BidIt
The iterator type for submatches.

Remarks

The class template describes an object that designates a sequence of characters that matched a capture group in a call to regex_match or to regex_search. Objects of type match_results Class hold an array of these objects, one for each capture group in the regular expression that was used in the search.

If the capture group wasn't matched the object's data member matched holds false, and the two iterators first and second (inherited from the base std::pair) are equal. If the capture group was matched, matched holds true, the iterator first points to the first character in the target sequence that matched the capture group, and the iterator second points one position past the last character in the target sequence that matched the capture group. For a zero-length match, the member matched holds true, the two iterators will be equal, and both will point to the position of the match.

A zero-length match can occur when a capture group consists solely of an assertion, or of a repetition that allows zero repeats. For example:

"^" matches the target sequence "a"; the sub_match object corresponding to capture group 0 holds iterators that both point to the first character in the sequence.

"b(a*)b" matches the target sequence "bb"; the sub_match object corresponding to capture group 1 holds iterators that both point to the second character in the sequence.

Typedefs

Type name	Description
difference_type	The type of an iterator difference.
iterator	The type of an iterator.
value_type	The type of an element.

Member functions

Member function	Description
compare	Compare submatch against a sequence.
length	Returns the length of a submatch.
matched	Indicates if match succeeded.
str	Converts submatch to a string.

Operators

Operator	Description
operator basic_string<value_type>	Casts submatch to a string.

Example

// std__regex__sub_match.cpp
// compile with: /EHsc
#include <regex>
#include <iostream>

int main()
    {
    std::regex rx("c(a*)|(b)");
    std::cmatch mr;

    std::regex_search("xcaaay", mr, rx);

    std::csub_match sub = mr[1];
    std::cout << "matched == " << std::boolalpha
        << sub.matched << std::endl;
    std::cout << "length == " << sub.length() << std::endl;

    std::csub_match::difference_type dif = std::distance(sub.first, sub.second);
    std::cout << "difference == " << dif << std::endl;

    std::csub_match::iterator first = sub.first;
    std::csub_match::iterator last = sub.second;
    std::cout << "range == " << std::string(first, last)
        << std::endl;
    std::cout << "string == " << sub << std::endl;

    std::csub_match::value_type const *ptr = "aab";
    std::cout << "compare(\"aab\") == "
        << sub.compare(ptr) << std::endl;
    std::cout << "compare(string) == "
        << sub.compare(std::string("AAA")) << std::endl;
    std::cout << "compare(sub) == "
        << sub.compare(sub) << std::endl;

    return (0);
    }

matched == true
length == 3
difference == 3
range == aaa
string == aaa
compare("aab") == -1
compare(string) == 1
compare(sub) == 0

Requirements

Header: <regex>

Namespace: std

sub_match::compare

Compare submatch against a sequence.

int compare(const sub_match& right) const;
int compare(const basic_string<value_type>& str) const;
int compare(const value_type *ptr) const;

Parameters

right
The submatch to compare to.

str
The string to compare to.

ptr
The null-terminated sequence to compare to.

Remarks

The first member function compares the matched sequence [first, second) to the matched sequence [right.first, right.second). The second member function compares the matched sequence [first, second) to the character sequence [right.begin(), right.end()). The third member function compares the matched sequence [first, second) to the character sequence [right, right + std::char_traits<value_type>::length(right)).

Each function returns:

a negative value if the first differing value in the matched sequence compares less than the corresponding element in the operand sequence (as determined by std::char_traits<value_type>::compare), or if the two have a common prefix but the target sequence is longer

zero if the two compare equal element by element and have the same length

a positive value otherwise

sub_match::difference_type

The type of an iterator difference.

typedef typename iterator_traits<BidIt>::difference_type difference_type;

Remarks

The typedef is a synonym for iterator_traits<BidIt>::difference_type.

sub_match::iterator

The type of an iterator.

typedef BidIt iterator;

Remarks

The typedef is a synonym for the template type argument Bidit.

sub_match::length

Returns the length of a submatch.

difference_type length() const;

Remarks

The member function returns the length of the matched sequence, or zero if there was no matched sequence.

sub_match::matched

Indicates if match succeeded.

bool matched;

Remarks

The member holds true only if the capture group associated with *this was part of the regular expression match.

sub_match::operator basic_string<value_type>

Casts submatch to a string.

operator basic_string<value_type>() const;

Remarks

The member operator returns str().

sub_match::str

Converts submatch to a string.

basic_string<value_type> str() const;

Remarks

The member function returns basic_string<value_type>(first, second).

sub_match::value_type

The type of an element.

typedef typename iterator_traits<BidIt>::value_type value_type;

Remarks

The typedef is a synonym for iterator_traits<BidIt>::value_type.

See also

<regex>
sub_match