Reference
<regex>
match_results

class template

<regex>

std::match_results

template < class BidirectionalIterator,           class Alloc = allocator< sub_match<BidirectionalIterator> > >  class match_results;

Match results

Container-like class used to store the matches found on the target sequence of characters after a regex matching operation, each match being of the corresponding sub_match type.

It is automatically filled by regex_match, regex_search or a regex_iterator with the results of the matching operation. The elements in match_results objects are const-qualified, and thus are not meant to be modified outside of these functions.

When constructed, match_results objects have no result state (i.e., they are not ready). Once they have been used as the proper argument in a call to either regex_match or regex_search, they acquire a established result state, and become ready (this can be checked by calling member function match_results::ready). Values returned by dereferencing a regex_iterator that points to a valid location are always ready.

Once ready, the object can either be empty or non-empty, depending on whether the target sequence was successfully matched against the expression. If successful, it is not empty and contains a series of sub_match objects: the first sub_match element corresponds to the entire match, and, if the regex expression contained sub-expressions to be matched (i.e., parentheses-delimited groups), their corresponding sub-matches are stored as successive sub_match elements in the match_results object.

These sub-matches can be accessed as if the match_results object were a container, or directly using members such as str, length or position.

If the match_results object was used with regex_search, the part of the target sequence that was not part of the match can be accessed using members prefix and suffix.

Objects of match_results type that are ready can also be used to format a character sequence using the information they contain by using member function match_results::format.

The classes cmatch and smatch are instantiations of this class for narrow characters (char). wcmatch and wsmatch are their respective wide character versions (wchar_t). Defined in the <regex> standard header as:

typedef match_results<const char*> cmatch;
typedef match_results<const wchar_t*> wcmatch;
typedef match_results<string::const_iterator> smatch;
typedef match_results<wstring::const_iterator> wsmatch;

Template parameters

BidirectionalIterator: A bidirectional iterator type that iterates on the target sequence of characters.
Alloc: Type of the allocator object used to define the storage allocation model. By default, the allocator class template is used for elements of type sub_match, which defines the simplest memory allocation model for these objects and is value-independent.
Aliased as member type match_results::allocator_type.

Template instantiations

cmatch: match_results for string literals (class)

smatch: match_results for string objects (class)

wcmatch: match_results for wide string literals (class)

wsmatch: match_results for wide string objects (class)

Member types

The following aliases are member types of match_results. They are widely used as parameter and return types by member functions:

member type	definition	notes
`value_type`	`sub_match<BidirectionalIterator>`	Type of the elements stored (sub_match).
`char_type`	`iterator_traits<BidirectionalIterator>::value_type`	Type of the characters in the sequence.
`string_type`	`basic_string<char_type>`	Type of string for the characters type.
`allocator_type`	the second template parameter (`Alloc`)	defaults to: `allocator<value_type>`
`reference`	`const value_type&`
`const_reference`	`const value_type&`
`iterator`	a forward iterator to `const value_type`
`const_iterator`	a forward iterator to `const value_type`	The same as `iterator`
`size_type`	`iterator_traits<BidirectionalIterator>::difference_type`	usually the same as size_t
`difference_type`	`iterator_traits<BidirectionalIterator>::size_type`	usually the same as ptrdiff_t

member type	definition	notes
`value_type`	`sub_match<BidirectionalIterator>`	Type of the elements stored (sub_match).
`char_type`	`iterator_traits<BidirectionalIterator>::value_type`	Type of the characters in the sequence.
`string_type`	`basic_string<char_type>`	Type of string for the characters type.
`allocator_type`	the second template parameter (`Alloc`)	defaults to: `allocator<value_type>`
`reference`	`value_type&`
`const_reference`	`const value_type&`
`iterator`	a forward iterator to `const value_type`
`const_iterator`	a forward iterator to `const value_type`	The same as `iterator`
`size_type`	`iterator_traits<BidirectionalIterator>::difference_type`	usually the same as size_t
`difference_type`	`iterator_traits<BidirectionalIterator>::size_type`	usually the same as ptrdiff_t

Member functions

(constructor): Construct match_results (public member function)

(destructor): Destroy match_results (public member function)

operator=: Assign value to match_results (public member function)

Capacity

empty: Test whether object has no matches (public member function)

size: Return number of matches (public member function)

max_size: Return maximum size (public member function)

Iterators

begin: Return iterator to beginning (public member function)

end: Return iterator to end (public member function)

cbegin: Return const_iterator to beginning (public member function)

cend: Return const_iterator to end (public member function)

Element access

operator[]: Return match (public member function)

prefix: Return prefix (public member function)

suffix: Return suffix (public member function)

length: Return length of match (public member function)

position: Return position of match (public member function)

str: Return match as a string (public member function)

Formatting

format: Format replacement string (public member function)

Swap

swap: Swap contents (public member function)

Observers

ready: Test whether results are ready (public member function)

get_allocator: Get allocator (public member function)

Non-member functions

operators (match_results): Relational operators for match_results (function template)

swap (match_results): Swap contents of two match_result objects (function template)

classes (basic)

classes (template instantiations)

functions

member functions

non-member functions