std::match_results (3) - Linux Manuals

std::match_results: std::match_results


std::match_results - std::match_results


Defined in header <regex>
class BidirIt, (1) (since C++11)
class Alloc = std::allocator<std::sub_match<BidirIt>>
> class match_results;
namespace pmr {
template <class BidirIt>
using match_results = std::match_results<BidirIt, (2) (since C++17)

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.
std::match_results meets the requirements of a AllocatorAwareContainer and of a SequenceContainer, except that only copy assignment, move assignment, and operations defined for a constant containers are supported, and that the semantics of comparison functions are different from those required for a container.

Type requirements

BidirIt must meet the requirements of LegacyBidirectionalIterator.
Alloc must meet the requirements of Allocator.


Several specializations for common character sequence types are provided:

Defined in header <regex>
Type Definition
std::cmatch std::match_results<const char*>
std::wcmatch std::match_results<const wchar_t*>
std::smatch std::match_results<std::string::const_iterator>
std::wsmatch std::match_results<std::wstring::const_iterator>
std::pmr::cmatch (C++17) std::pmr::match_results<const char*>
std::pmr::wcmatch (C++17) std::pmr::match_results<const wchar_t*>
std::pmr::smatch (C++17) std::pmr::match_results<std::string::const_iterator>
std::pmr::wsmatch (C++17) std::pmr::match_results<std::wstring::const_iterator>

Member types

Member type Definition
allocator_type Allocator
value_type std::sub_match<BidirIt>
const_reference const value_type&
reference value_type&
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>

Member functions

              constructs the object
constructor (public member function)
              destructs the object
destructor (public member function)
              assigns the contents
operator= (public member function)
              returns the associated allocator
get_allocator (public member function)


              checks if the results are available
ready (public member function)


              checks whether the match was successful
empty (public member function)
              returns the number of matches in a fully-established result state
size (public member function)
              returns the maximum possible number of sub-matches
max_size (public member function)

Element access

              returns the length of the particular sub-match
length (public member function)
              returns the position of the first character of the particular sub-match
position (public member function)
              returns the sequence of characters for the particular sub-match
str (public member function)
              returns specified sub-match
operator[] (public member function)
              returns sub-sequence between the beginning of the target sequence and the beginning of the full match.
prefix (public member function)
              returns sub-sequence between the end of the full match and the end of the target sequence
suffix (public member function)


              returns iterator to the beginning of the list of sub-matches
begin (public member function)
              returns iterator to the end of the list of sub-matches
end (public member function)


              formats match results for output
format (public member function)


              swaps the contents
swap (public member function)

Non-member functions

                              lexicographically compares the values in the two match result
operator== (function template)

std::swap(std::match_results) specializes the std::swap() algorithm
                              (function template)