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:
1
2
3
4
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


Member types

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

member typedefinitionnotes
value_typesub_match<BidirectionalIterator>Type of the elements stored (sub_match).
char_typeiterator_traits<BidirectionalIterator>::value_typeType of the characters in the sequence.
string_typebasic_string<char_type>Type of string for the characters type.
allocator_typethe second template parameter (Alloc)defaults to: allocator<value_type>
referenceconst value_type&
const_referenceconst value_type&
iteratora forward iterator to const value_type
const_iteratora forward iterator to const value_typeThe same as iterator
size_typeiterator_traits<BidirectionalIterator>::difference_typeusually the same as size_t
difference_typeiterator_traits<BidirectionalIterator>::size_typeusually the same as ptrdiff_t
member typedefinitionnotes
value_typesub_match<BidirectionalIterator>Type of the elements stored (sub_match).
char_typeiterator_traits<BidirectionalIterator>::value_typeType of the characters in the sequence.
string_typebasic_string<char_type>Type of string for the characters type.
allocator_typethe second template parameter (Alloc)defaults to: allocator<value_type>
referencevalue_type&
const_referenceconst value_type&
iteratora forward iterator to const value_type
const_iteratora forward iterator to const value_typeThe same as iterator
size_typeiterator_traits<BidirectionalIterator>::difference_typeusually the same as size_t
difference_typeiterator_traits<BidirectionalIterator>::size_typeusually the same as ptrdiff_t

Member functions


Capacity


Iterators


Element access


Formatting


Swap


Observers


Non-member functions