match_results Class

Holds a sequence of submatches.

Syntax

template <class BidIt, class Alloc>
class match_results

Parameters

BidIt
The iterator type for submatches.

Alloc
The type of an allocator for managing storage.

Remarks

The template class describes an object that controls a non-modifiable sequence of elements of type sub_match<BidIt> generated by a regular expression search. Each element points to the subsequence that matched the capture group corresponding to that element.

Constructors

Constructor Description
match_results Constructs the object.

Typedefs

Type name Description
allocator_type The type of an allocator for managing storage.
char_type The type of an element.
const_iterator The const iterator type for submatches.
const_reference The type of an element const reference.
difference_type The type of an iterator difference.
iterator The iterator type for submatches.
reference The type of an element reference.
size_type The type of a submatch count.
string_type The type of a string.
value_type The type of a submatch.

Member functions

Member function Description
begin Designates beginning of submatch sequence.
empty Tests for no submatches.
end Designates end of submatch sequence.
format Formats submatches.
get_allocator Returns the stored allocator.
length Returns length of a submatch.
max_size Gets largest number of submatches.
position Get starting offset of a subgroup.
prefix Gets sequence before first submatch.
size Counts number of submatches.
str Returns a submatch.
suffix Gets sequence after last submatch.
swap Swaps two match_results objects.

Operators

Operator Description
operator= Copy a match_results object.
operator[] Access a subobject.

Requirements

Header: <regex>

Namespace: std

Example

// std__regex__match_results.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::cout << "prefix: matched == " << std::boolalpha
        << mr.prefix().matched
        << ", value == " << mr.prefix() << std::endl;
    std::cout << "whole match: " << mr.length() << " chars, value == "
        << mr.str() << std::endl;
    std::cout << "suffix: matched == " << std::boolalpha
        << mr.suffix().matched
        << ", value == " << mr.suffix() << std::endl;
    std::cout << std::endl;

    std::string fmt("\"c(a*)|(b)\" matched \"$&\"\n"
        "\"(a*)\" matched \"$1\"\n"
        "\"(b)\" matched \"$2\"\n");
    std::cout << mr.format(fmt) << std::endl;
    std::cout << std::endl;

    // index through submatches
    for (size_t n = 0; n < mr.size(); ++n)
    {
        std::cout << "submatch[" << n << "]: matched == " << std::boolalpha
            << mr[n].matched <<
            " at position " << mr.position(n) << std::endl;
        std::cout << "  " << mr.length(n)
            << " chars, value == " << mr[n] << std::endl;
    }
    std::cout << std::endl;

    // iterate through submatches
    for (std::cmatch::iterator it = mr.begin(); it != mr.end(); ++it)
    {
        std::cout << "next submatch: matched == " << std::boolalpha
            << it->matched << std::endl;
        std::cout << "  " << it->length()
            << " chars, value == " << *it << std::endl;
    }
    std::cout << std::endl;

    // other members
    std::cout << "empty == " << std::boolalpha << mr.empty() << std::endl;

    std::cmatch::allocator_type al = mr.get_allocator();
    std::cmatch::string_type str = std::string("x");
    std::cmatch::size_type maxsiz = mr.max_size();
    std::cmatch::char_type ch = 'x';
    std::cmatch::difference_type dif = mr.begin() - mr.end();
    std::cmatch::const_iterator cit = mr.begin();
    std::cmatch::value_type val = *cit;
    std::cmatch::const_reference cref = val;
    std::cmatch::reference ref = val;

    maxsiz = maxsiz;  // to quiet "unused" warnings
    if (ref == cref)
        ch = ch;
    dif = dif;

    return (0);
}
prefix: matched == true, value == x
whole match: 4 chars, value == caaa
suffix: matched == true, value == y

"c(a*)|(b)" matched "caaa"
"(a*)" matched "aaa"
"(b)" matched ""

submatch[0]: matched == true at position 1
  4 chars, value == caaa
submatch[1]: matched == true at position 2
  3 chars, value == aaa
submatch[2]: matched == false at position 6
  0 chars, value ==

next submatch: matched == true
  4 chars, value == caaa
next submatch: matched == true
  3 chars, value == aaa
next submatch: matched == false
  0 chars, value ==

empty == false

match_results::allocator_type

The type of an allocator for managing storage.

typedef Alloc allocator_type;

Remarks

The typedef is a synonym for the template argument Alloc.

match_results::begin

Designates beginning of submatch sequence.

const_iterator begin() const;

Remarks

The member function returns a random access iterator that points at the first element of the sequence (or just beyond the end of an empty sequence).

match_results::char_type

The type of an element.

typedef typename iterator_traits<BidIt>::value_type char_type;

Remarks

The typedef is a synonym for the type iterator_traits<BidIt>::value_type, which is the element type of the character sequence that was searched.

match_results::const_iterator

The const iterator type for submatches.

typedef T0 const_iterator;

Remarks

The typedef describes an object that can serve as a constant random-access iterator for the controlled sequence.

match_results::const_reference

The type of an element const reference.

typedef const typename Alloc::const_reference const_reference;

Remarks

The typedef describes an object that can serve as a constant reference to an element of the controlled sequence.

match_results::difference_type

The type of an iterator difference.

typedef typename iterator_traits<BidIt>::difference_type difference_type;

Remarks

The typedef is a synonym for the type iterator_traits<BidIt>::difference_type; it describes an object that can represent the difference between any two iterators that point at elements of the controlled sequence.

match_results::empty

Tests for no submatches.

bool empty() const;

Remarks

The member function returns true only if the regular expression search failed.

match_results::end

Designates end of submatch sequence.

const_iterator end() const;

Remarks

The member function returns an iterator that points just beyond the end of the sequence.

match_results::format

Formats submatches.

template <class OutIt>
OutIt format(OutIt out,
    const string_type& fmt, match_flag_type flags = format_default) const;

string_type format(const string_type& fmt, match_flag_type flags = format_default) const;

Parameters

OutIt
The output iterator type.

out
The output stream to write to.

fmt
The format string.

flags
The format flags.

Remarks

Each member function generates formatted text under the control of the format fmt. The first member function writes the formatted text to the sequence defined by its argument out and returns out. The second member function returns a string object holding a copy of the formatted text.

To generate formatted text. literal text in the format string is ordinarily copied to the target sequence. Each escape sequence in the format string is replaced by the text that it represents. The details of the copying and replacement are controlled by the format flags passed to the function.

match_results::get_allocator

Returns the stored allocator.

allocator_type get_allocator() const;

Remarks

The member function returns a copy of the allocator object used by *this to allocate its sub_match objects.

match_results::iterator

The iterator type for submatches.

typedef const_iterator iterator;

Remarks

The type describes an object that can serve as a random-access iterator for the controlled sequence.

match_results::length

Returns length of a submatch.

difference_type length(size_type sub = 0) const;

Parameters

sub
The index of the submatch.

Remarks

The member function returns (*this)[sub].length().

match_results::match_results

Constructs the object.

explicit match_results(const Alloc& alloc = Alloc());

match_results(const match_results& right);

Parameters

alloc
The allocator object to store.

right
The match_results object to copy.

Remarks

The first constructor constructs a match_results object that holds no submatches. The second constructor constructs a match_results object that is a copy of right.

match_results::max_size

Gets largest number of submatches.

size_type max_size() const;

Remarks

The member function returns the length of the longest sequence that the object can control.

match_results::operator=

Copy a match_results object.

match_results& operator=(const match_results& right);

Parameters

right
The match_results object to copy.

Remarks

The member operator replaces the sequence controlled by *this with a copy of the sequence controlled by right.

match_results::operator[]

Access a subobject.

const_reference operator[](size_type n) const;

Parameters

n
Index of the submatch.

Remarks

The member function returns a reference to element n of the controlled sequence, or a reference to an empty sub_match object if size() <= n or if capture group n was not part of the match.

match_results::position

Get starting offset of a subgroup.

difference_type position(size_type sub = 0) const;

Parameters

sub
Index of the submatch.

Remarks

The member function returns std::distance(prefix().first, (*this)[sub].first), that is, the distance from the first character in the target sequence to the first character in the submatch pointed to by element n of the controlled sequence.

match_results::prefix

Gets sequence before first submatch.

const_reference prefix() const;

Remarks

The member function returns a reference to an object of type sub_match<BidIt> that points to the character sequence that begins at the start of the target sequence and ends at (*this)[0].first, that is, it points to the text that precedes the matched subsequence.

match_results::reference

The type of an element reference.

typedef const_reference reference;

Remarks

The type is a synonym for the type const_reference.

match_results::size

Counts number of submatches.

size_type size() const;

Remarks

The member function returns one more than the number of capture groups in the regular expression that was used for the search, or zero if no search has been made.

match_results::size_type

The type of a submatch count.

typedef typename Alloc::size_type size_type;

Remarks

The type is a synonym for the type Alloc::size_type.

match_results::str

Returns a submatch.

string_type str(size_type sub = 0) const;

Parameters

sub
Index of the submatch.

Remarks

The member function returns string_type((*this)[sub]).

match_results::string_type

The type of a string.

typedef basic_string<char_type> string_type;

Remarks

The type is a synonym for the type basic_string<char_type>.

match_results::suffix

Gets sequence after last submatch.

const_reference suffix() const;

Remarks

The member function returns a reference to an object of type sub_match<BidIt> that points to the character sequence that begins at (*this)[size() - 1].second and ends at the end of the target sequence, that is, it points to the text that follows the matched subsequence.

match_results::swap

Swaps two match_results objects.

void swap(const match_results& right) throw();

Parameters

right
The match_results object to swap with.

Remarks

The member function swaps the contents of *this and right in constant time and does not throw exceptions.

match_results::value_type

The type of a submatch.

typedef sub_match<BidIt> value_type;

Remarks

The typedef is a synonym for the type sub_match<BidIt>.

See also

<regex>