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 class template 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 wasn't 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 doesn't 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>.