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

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 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

(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 )

C++