Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/regex/match results"

From cppreference.com
< cpp‎ | regex
m (Update links.)
m (fmt)
 
(15 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{cpp/title|match_results}}
 
{{cpp/title|match_results}}
 
{{cpp/regex/match_results/navbar}}
 
{{cpp/regex/match_results/navbar}}
−
{{ddcl | header=regex | notes={{mark since c++11}} | 1=
+
{{
 +
header|
 +
{{sincec++11|1=
 
template<
 
template<
 
     class BidirIt,
 
     class BidirIt,
Line 7: Line 9:
 
> class match_results;
 
> class match_results;
 
}}
 
}}
 +
 +
 +
 +
 +
 +
 +
 +
 +
  
−
The class template {{lc|std::match_results}} holds a collection of character sequences that represent the result of a regular expression match.
+
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 {{lc|std::regex_iterator}}, or modified by {{lc|std::regex_search}} or {{lc|std::regex_match}}. Because {{tt|std::match_results}} holds {{lc|std::sub_match}}es, each of which is a pair of iterators into the original character sequence that was matched, it's undefined behavior to examine {{tt|std::match_results}} if the original character sequence was destroyed or iterators to it were invalidated for other reasons.
+
This is a specialized allocator-aware container. It can only be default created, obtained from {{lc|std::regex_iterator}}, or modified by {{lc|std::regex_search}} or {{lc|std::regex_match}}. Because {{tt|std::match_results}} holds {{lc|std::sub_match}}es, each of which is a pair of iterators into the original character sequence that was matched, it's undefined behavior to examine {{tt|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.
+
The first sub_match(index 0) contained in a match_resultalways represents the full match within a target sequence made by a regex, and subsequent represent sub-expression matches corresponding in sequence to the left parenthesis delimiting the sub-expression in the regex
 +
 
 +
.
  
 
===Type requirements===
 
===Type requirements===
 
{{par begin}}
 
{{par begin}}
−
{{par req concept | BidirIt | BidirectionalIterator}}
+
{{par req |BidirIt|BidirectionalIterator}}
−
{{par req concept | Alloc | Allocator}}
+
{{par req |Alloc|Allocator}}
 
{{par end}}
 
{{par end}}
  
Line 24: Line 37:
  
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc header | regex}}
+
{{dsc header|regex}}
−
{{dsc hitem | Type | Definition}}
+
{{dsc hitem|Type|Definition}}
−
{{dsc | {{tt|cmatch}} | {{c|match_results<const char*>}}}}
+
{{dsc|{{tt|cmatch}}|{{c|match_results<const char*>}}}}
−
{{dsc | {{tt|wcmatch}} | {{c|match_results<const wchar_t*>}}}}
+
{{dsc|{{tt|wcmatch}}|{{c|match_results<const wchar_t*>}}}}
−
{{dsc | {{tt|smatch}} | {{c|match_results<std::string::const_iterator>}}}}
+
{{dsc|{{tt|smatch}}|{{c|match_results<std::string::const_iterator>}}}}
−
{{dsc | {{tt|wsmatch}} | {{c|match_results<std::wstring::const_iterator>}}}}
+
{{dsc|{{tt|wsmatch}}|{{c|
 +
 +
 +
 +
match_results<std::wstring::const_iterator>}}}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Member types===
 
===Member types===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc hitem | Member type | Definition}}
+
{{dsc hitem|Member type|Definition}}
−
{{dsc | {{tt|allocator_type}} | {{c|Allocator}}}}
+
{{dsc|{{tt|allocator_type}}|{{|Allocator}}}}
−
{{dsc | {{tt|value_type}} | {{c|std::sub_match<BidirIt>}}}}
+
{{dsc|{{tt|value_type}}|{{c|std::sub_match<BidirIt>}}}}
−
{{dsc | {{tt|const_reference}} | {{c|const value_type&}}}}
+
{{dsc|{{tt|const_reference}}|{{c|const value_type&}}}}
−
{{dsc | {{tt|reference}} | {{c|const_reference}}}}
+
{{dsc|{{tt|reference}}|{{|}}}}
−
{{dsc | {{tt|const_iterator}} | ''implementation defined'' (depends on the underlying container)}}
+
{{dsc|{{tt|const_iterator}}|''implementationdefined'' (depends on the underlying container)}}
−
{{dsc | {{tt|iterator}} | {{c|const_iterator}}}}
+
{{dsc|{{tt|iterator}}|{{|const_iterator}}}}
−
{{dsc | {{tt|difference_type}} | {{c|std::iterator_traits<BidirIt>::difference_type}}}}
+
{{dsc|{{tt|difference_type}}|{{c|std::iterator_traits<BidirIt>::difference_type}}}}
−
{{dsc | {{tt|size_type}} | {{c|std::allocator_traits<Alloc>::size_type}}}}
+
{{dsc|{{tt|size_type}}|{{c|std::allocator_traits<Alloc>::size_type}}}}
−
{{dsc | {{tt|char_type}} | {{c|std::iterator_traits<BidirIt>::value_type}}}}
+
{{dsc|{{tt|char_type}}|{{c|std::iterator_traits<BidirIt>::value_type}}}}
−
{{dsc | {{tt|string_type}} | {{c|std::basic_string<char_type>}}}}
+
{{dsc|{{tt|string_type}}|{{c|std::basic_string<char_type>}}}}
 
{{dsc end}}
 
{{dsc end}}
  
 
===Member functions===
 
===Member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/regex/match_results/dsc constructor}}
+
{{dsc inc|cpp/regex/match_results/dsc constructor}}
−
{{dsc inc | cpp/regex/match_results/dsc destructor}}
+
{{dsc inc|cpp/regex/match_results/dsc destructor}}
−
{{dsc inc | cpp/regex/match_results/dsc operator{{=}}}}
+
{{dsc inc|cpp/regex/match_results/dsc operator{{=}}}}
−
{{dsc inc | cpp/regex/match_results/dsc get_allocator}}
+
{{dsc inc|cpp/regex/match_results/dsc get_allocator}}
−
 
+
−
{{dsc h2 | State}}
+
−
{{dsc mem fun | cpp/regex/match_results/ready | }}
+
  
−
{{dsc h2 | Size}}
+
{{dsc h2|}}
−
{{dsc inc | cpp/regex/match_results/dsc empty}}
+
{{dsc |cpp/regex/match_results/|}}
−
{{dsc inc | cpp/regex/match_results/dsc size}}
+
−
{{dsc inc | cpp/regex/match_results/dsc max_size}}
+
  
−
{{dsc h2 | Element access}}
+
{{dsc h2|}}
−
{{dsc inc | cpp/regex/match_results/dsc length}}
+
{{dsc inc|cpp/regex/match_results/dsc }}
−
{{dsc inc | cpp/regex/match_results/dsc position}}
+
{{dsc inc|cpp/regex/match_results/dsc }}
−
{{dsc inc | cpp/regex/match_results/dsc str}}
+
{{dsc inc|cpp/regex/match_results/dsc }}
−
{{dsc inc | cpp/regex/match_results/dsc operator_at}}
+
−
{{dsc inc | cpp/regex/match_results/dsc prefix}}
+
−
{{dsc inc | cpp/regex/match_results/dsc suffix}}
+
  
−
{{dsc h2 | Iterators}}
+
{{dsc h2|}}
−
{{dsc inc | cpp/regex/match_results/dsc begin}}
+
{{dsc inc|cpp/regex/match_results/dsc }}
−
{{dsc inc | cpp/regex/match_results/dsc end}}
+
{{dsc inc|cpp/regex/match_results/dsc
 +
 +
 +
 +
}}
  
−
{{dsc h2 | Format}}
+
{{dsc h2|}}
−
{{dsc inc | cpp/regex/match_results/dsc format}}
+
{{dsc inc|cpp/regex/match_results/dsc
 +
}}
  
−
{{dsc h2 | Modifiers}}
+
{{dsc h2|}}
−
{{dsc inc | cpp/regex/match_results/dsc swap}}
+
{{dsc inc|cpp/regex/match_results/dsc }}
  
 +
 +
 
{{dsc end}}
 
{{dsc end}}
  
 
===Non-member functions===
 
===Non-member functions===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/regex/match_results/dsc operator_cmp}}
+
{{dsc inc|cpp/regex/match_results/dsc operator_cmp}}
−
{{dsc inc | cpp/regex/match_results/dsc swap2}}
+
{{dsc inc|cpp/regex/match_results/dsc swap2}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/regex/match results]]
+
deesfritjaptruzh
−
[[es:cpp/regex/match results]]
+
−
[[fr:cpp/regex/match results]]
+
−
[[it:cpp/regex/match results]]
+
−
[[ja:cpp/regex/match results]]
+
−
[[pt:cpp/regex/match results]]
+
−
[[ru:cpp/regex/match results]]
+
−
[[zh:cpp/regex/match results]]
+

Latest revision as of 07:15, 25 December 2023

 
C++
 
Text processing library
 
Regular expressions library
Classes
(C++11)
(C++11)
match_results
(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::match_results
 
Defined in header <regex>
template<

    class BidirIt,
    class Alloc = std::allocator<std::sub_match<BidirIt>>

> class match_results;
 (1) (since C++11)
namespace pmr {

    template <class BidirIt>
    using match_results = std::match_results<BidirIt,
                              std::pmr::polymorphic_allocator<
                                  std::sub_match<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 std::sub_match (index 0) contained in a std::match_result always represents the full match within a target sequence made by a regex, and subsequent std::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.

Contents

[edit] Type requirements

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

[edit] 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>

[edit] 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>

[edit] Member functions

 constructs the object
(public member function) [edit]
destructs the object
(public member function) [edit]
assigns the contents
(public member function) [edit]
returns the associated allocator
(public member function) [edit]
State
checks if the results are available
(public member function)
Size
checks whether the match was successful
(public member function) [edit]
returns the number of matches in a fully-established result state
(public member function) [edit]
returns the maximum possible number of sub-matches
(public member function) [edit]
Element access
returns the length of the particular sub-match
(public member function) [edit]
returns the position of the first character of the particular sub-match
(public member function) [edit]
returns the sequence of characters for the particular sub-match
(public member function) [edit]
returns specified sub-match
(public member function) [edit]
returns sub-sequence between the beginning of the target sequence and the beginning of the full match
(public member function) [edit]
returns sub-sequence between the end of the full match and the end of the target sequence
(public member function) [edit]
Iterators
returns iterator to the beginning of the list of sub-matches
(public member function) [edit]
returns iterator to the end of the list of sub-matches
(public member function) [edit]
Format
formats match results for output
(public member function) [edit]
Modifiers
swaps the contents
(public member function) [edit]

[edit] Non-member functions

(removed in C++20)
 lexicographically compares the values in the two match result
(function template) [edit]
(C++11)
 specializes the std::swap algorithm
(function template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/regex/match_results&oldid=167116"