##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::match_results

From cppreference.com
< cpp‎ | regex

Defined in header `<regex>` |  |
template< class BidirIt, class Alloc = std::allocator<std::sub_match<BidirIt>> > class match_results; |  | (since C++11)

The class template std::match_results holds a collection of character sequences that represent the result of a regular expression match.

This is a specialized allocator-aware container. It can only be default created, obtained from std::regex_iterator, or modified by std::regex_search or std::regex_match. Because `std::match_results` holds std::sub_matches, each of which is a pair of iterators into the original character sequence that was matched, it's undefined behavior to examine `std::match_results` if the original character sequence was destroyed or iterators to it were invalidated for other reasons.

The first sub_match (index 0) contained in a match_result always represents the full match within a target sequence made by a regex, and subsequent sub_matches represent sub-expression matches corresponding in sequence to the left parenthesis delimiting the sub-expression in the regex.

### [edit] Type requirements

- `BidirIt` must meet the requirements of `BidirectionalIterator`.
- `Alloc` must meet the requirements of `Allocator`.

### [edit] Specializations

Several specializations for common character sequence types are provided:

Defined in header `<regex>`
Type | Definition
`cmatch` | match_results<const char*>
`wcmatch` | match_results<const wchar_t*>
`smatch` | match_results<std::string::const_iterator>
`wsmatch` | match_results<std::wstring::const_iterator>

### [edit] Member types

Member type | Definition
`allocator_type` | Allocator
`value_type` | std::sub_match<BidirIt>
`const_reference` | const value_type&
`reference` | const_reference
`const_iterator` | implementation defined (depends on the underlying container)
`iterator` | const_iterator
`difference_type` | std::iterator_traits<BidirIt>::difference_type
`size_type` | std::allocator_traits<Alloc>::size_type
`char_type` | std::iterator_traits<BidirIt>::value_type
`string_type` | std::basic_string<char_type>

### [edit] Member functions

(constructor) | constructs the object (public member function) [edit]
(destructor) | destructs the object (public member function) [edit]
operator= | assigns the contents (public member function) [edit]
get_allocator | returns the associated allocator (public member function) [edit]
##### State
ready | checks if the results are available (public member function)
##### Size
empty | checks whether the match was successful (public member function) [edit]
size | returns the number of matches in a fully-established result state (public member function) [edit]
max_size | returns the maximum possible number of sub-matches (public member function) [edit]
##### Element access
length | returns the length of the particular sub-match (public member function) [edit]
position | returns the position of the first character of the particular sub-match (public member function) [edit]
str | returns the sequence of characters for the particular sub-match (public member function) [edit]
operator[] | returns specified sub-match (public member function) [edit]
prefix | returns sub-sequence between the beginning of the target sequence and the beginning of the full match. (public member function) [edit]
suffix | returns sub-sequence between the end of the full match and the end of the target sequence (public member function) [edit]
##### Iterators
begin cbegin | returns iterator to the beginning of the list of sub-matches (public member function) [edit]
end cend | returns iterator to the end of the list of sub-matches (public member function) [edit]
##### Format
format | formats match results for output (public member function) [edit]
##### Modifiers
swap | swaps the contents (public member function) [edit]

### [edit] Non-member functions

operator==operator!= | lexicographically compares the values in the two match result (function template) [edit]
std::swap(std::match_results) (C++11) | specializes the `std::swap()` algorithm (function template) [edit]

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/regex/match_results&oldid=66574"