Namespaces
Variants

std:: sub_match

From cppreference.net
C++
Text processing library
Regular expressions library
Classes
(C++11)
sub_match
(C++11)
(C++11)
Algorithms
(C++11)
(C++11)
(C++11)
Iterators
(C++11)
(C++11)
Exceptions
(C++11)
Traits
(C++11)
Constants
(C++11)
(C++11)
(C++11)
Regex Grammar
(C++11)
std::sub_match
Defined in header <regex>
template < class BidirIt >
class sub_match ;
(since C++11)

The class template std::sub_match is used by the regular expression engine to denote sequences of characters matched by marked sub-expressions. A match is a [ begin , end ) pair within the target range matched by the regular expression, but with additional observer functions to enhance code clarity.

Only the default constructor is publicly accessible. Instances of std::sub_match are normally constructed and populated as a part of a std::match_results container during the processing of one of the regex algorithms.

The member functions return defined default values unless the matched member is true .

std::sub_match inherits from std:: pair < BidirIt, BidirIt > , although it cannot be treated as a std::pair object because member functions such as assignment will not work as expected.

Contents

Type requirements

-
BidirIt must meet the requirements of LegacyBidirectionalIterator .

Specializations

Several specializations for common character sequence types are provided:

Defined in header <regex>
Type Definition
std::csub_match std :: sub_match < const char * >
std::wcsub_match std :: sub_match < const wchar_t * >
std::ssub_match std :: sub_match < std :: string :: const_iterator >
std::wssub_match std :: sub_match < std :: wstring :: const_iterator >

Nested types

Type Definition
iterator BidirIt
value_type std:: iterator_traits < BidirIt > :: value_type
difference_type std:: iterator_traits < BidirIt > :: difference_type
string_type std:: basic_string < value_type >

Data members

Member Description
bool matched
whether this match was successful
(public member object)

Inherited from std:: pair

BidirIt first
start of the match sequence
(public member object)
BidirIt second
one-past-the-end of the match sequence
(public member object)

Member functions

constructs the match object
(public member function)
Observers
returns the length of the match (if any)
(public member function)
converts to the underlying string type
(public member function)
compares matched subsequence (if any)
(public member function)
Modifiers
swaps the contents
(public member function)

Non-member functions

(removed in C++20) (removed in C++20) (removed in C++20) (removed in C++20) (removed in C++20) (C++20)
compares a sub_match with another sub_match , a string, or a character
(function template)
outputs the matched character subsequence
(function template)

Example

Run this code 
#include <cassert>
#include <iostream>
#include <regex>
#include <string>
int main()
{
    std::string sentence{"Friday the thirteenth."};
    const std::regex re{"([A-z]+) ([a-z]+) ([a-z]+)"};
    std::smatch words;
    std::regex_search(sentence, words, re);
    std::cout << std::boolalpha;
    for (const auto& m : words)
    {
        assert(m.matched);
        std::cout << "m: [" << m << "], m.length(): " << m.length() << ", "
                     "*m.first: '" << *m.first << "', "
                     "*m.second: '" << *m.second << "'\n";
    }
}

Output: 

m: [Friday the thirteenth], m.length(): 21, *m.first: 'F', *m.second: '.'
m: [Friday], m.length(): 6, *m.first: 'F', *m.second: ' '
m: [the], m.length(): 3, *m.first: 't', *m.second: ' '
m: [thirteenth], m.length(): 10, *m.first: 't', *m.second: '.'

See also

(C++11)
iterates through the specified sub-expressions within all regex matches in a given string or through unmatched substrings
(class template)