std::match_results (3) - Linux Manuals

std::match_results: std::match_results

NAME

std::match_results - std::match_results

Synopsis

Defined in header <regex>
template<
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)
std::pmr::polymorphic_allocator<
std::sub_match<BidirIt>>>;
}

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.

Specializations

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)

State

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

Size

              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)

Iterators

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

Format

              formats match results for output
format (public member function)

Modifiers

              swaps the contents
swap (public member function)

Non-member functions

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

std::swap(std::match_results) specializes the std::swap() algorithm
                              (function template)
(C++11)