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

From cppreference.com

Latest revision as of 07:15, 25 December 2023

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.

1 Type requirements
2 Specializations
3 Member types
4 Member functions
5 Non-member functions

[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

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

[edit] Non-member functions

operator==operator!= (removed in C++20)	lexicographically compares the values in the two match result (function template) [edit]
std::swap(std::match_results) (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"

@@ Line 3: / Line 3: @@
 {{dcl begin}}
 {{dcl header|regex}}
-{{dcl | num=1| since=c++11 | 1=
+{{dcl|num=1|since=c++11|1=
 template<
      class BidirIt,
@@ Line 11: / Line 11: @@
 {{dcl|num=2|since=c++17|1=
 namespace pmr {
-     template <class BidirectionalIterator>
+     template <class >
      using match_results = std::match_results<BidirIt,
-        std::polymorphic_allocator<std::sub_match<BidirIt>>>;
+std::polymorphic_allocator<
+std::sub_match<BidirIt>>>;
 }
 }}
 {{dcl end}}
-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 {{tt|sub_match}} (index 0) contained in a {{tt|match_result}} always represents the full match within a target sequence made by a regex, and subsequent {{tt|sub_match}}es 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 {{tt|match_result}} always represents the full match within a target sequence made by a regex, and subsequent {{|sub_match}}es represent sub-expression matches corresponding in sequence to the left parenthesis delimiting the sub-expression in the regex.
-{{tt|std::match_results}} meets the requirements of a constant {{concept|AllocatorAwareContainer}} and of a constant {{concept|SequenceContainer}}, except that the semantics of comparison functions are different from those required for a container.
+{{tt|std::match_results}} meets the requirements of a {{|AllocatorAwareContainer}} and of a {{|SequenceContainer}}, except that the semantics of comparison functions are different from those required for a container.
 ===Type requirements===
 {{par begin}}
-{{par req concept | BidirIt | BidirectionalIterator}}
+{{par req |BidirIt|BidirectionalIterator}}
-{{par req concept | Alloc | Allocator}}
+{{par req |Alloc|Allocator}}
 {{par end}}
@@ Line 36: / Line 37: @@
 {{dsc begin}}
-{{dsc header | regex}}
+{{dsc header|regex}}
-{{dsc hitem | Type | Definition}}
+{{dsc hitem|Type|Definition}}
-{{dsc | {{tt|std::cmatch}} | {{c|std::match_results<const char*>}}}}
+{{dsc|{{tt|std::cmatch}}|{{c|std::match_results<const char*>}}}}
-{{dsc | {{tt|std::wcmatch}} | {{c|std::match_results<const wchar_t*>}}}}
+{{dsc|{{tt|std::wcmatch}}|{{c|std::match_results<const wchar_t*>}}}}
-{{dsc | {{tt|std::smatch}} | {{c|std::match_results<std::string::const_iterator>}}}}
+{{dsc|{{tt|std::smatch}}|{{c|std::match_results<std::string::const_iterator>}}}}
-{{dsc | {{tt|std::wsmatch}} | {{c|std::match_results<std::wstring::const_iterator>}}}}
+{{dsc|{{tt|std::wsmatch}}|{{c|std::match_results<std::wstring::const_iterator>}}}}
-{{dsc | {{tt|std::pmr::cmatch}} {{mark c++17}} | {{c|std::pmr::match_results<const char*>}}}}
+{{dsc|{{tt|std::pmr::cmatch}} {{mark c++17}}|{{c|std::pmr::match_results<const char*>}}}}
-{{dsc | {{tt|std::pmr::wcmatch}} {{mark c++17}}| {{c|std::pmr::match_results<const wchar_t*>}}}}
+{{dsc|{{tt|std::pmr::wcmatch}} {{mark c++17}}|{{c|std::pmr::match_results<const wchar_t*>}}}}
-{{dsc | {{tt|std::pmr::smatch}} {{mark c++17}}| {{c|std::pmr::match_results<std::string::const_iterator>}}}}
+{{dsc|{{tt|std::pmr::smatch}} {{mark c++17}}|{{c|std::pmr::match_results<std::string::const_iterator>}}}}
-{{dsc | {{tt|std::pmr::wsmatch}} {{mark c++17}}| {{c|std::pmr::match_results<std::wstring::const_iterator>}}}}
+{{dsc|{{tt|std::pmr::wsmatch}} {{mark c++17}}|{{c|std::pmr::match_results<std::wstring::const_iterator>}}}}
 {{dsc end}}
 ===Member types===
 {{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|value_type&}}}}
+{{dsc|{{tt|reference}}|{{|value_type&}}}}
-{{dsc | {{tt|const_iterator}} | {{c|/*depends on the underlying container*/}}}}
+{{dsc|{{tt|const_iterator}}|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}}
 ===Member functions===
 {{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 h2|State}}
-{{dsc mem fun | cpp/regex/match_results/ready | checks if the results are available}}
+{{dsc mem fun|cpp/regex/match_results/ready|checks if the results are available}}
-{{dsc h2 | Size}}
+{{dsc h2|Size}}
-{{dsc inc | cpp/regex/match_results/dsc empty}}
+{{dsc inc|cpp/regex/match_results/dsc empty}}
-{{dsc inc | cpp/regex/match_results/dsc size}}
+{{dsc inc|cpp/regex/match_results/dsc size}}
-{{dsc inc | cpp/regex/match_results/dsc max_size}}
+{{dsc inc|cpp/regex/match_results/dsc max_size}}
-{{dsc h2 | Element access}}
+{{dsc h2|Element access}}
-{{dsc inc | cpp/regex/match_results/dsc length}}
+{{dsc inc|cpp/regex/match_results/dsc length}}
-{{dsc inc | cpp/regex/match_results/dsc position}}
+{{dsc inc|cpp/regex/match_results/dsc position}}
-{{dsc inc | cpp/regex/match_results/dsc str}}
+{{dsc inc|cpp/regex/match_results/dsc str}}
-{{dsc inc | cpp/regex/match_results/dsc operator_at}}
+{{dsc inc|cpp/regex/match_results/dsc operator_at}}
-{{dsc inc | cpp/regex/match_results/dsc prefix}}
+{{dsc inc|cpp/regex/match_results/dsc prefix}}
-{{dsc inc | cpp/regex/match_results/dsc suffix}}
+{{dsc inc|cpp/regex/match_results/dsc suffix}}
-{{dsc h2 | Iterators}}
+{{dsc h2|Iterators}}
-{{dsc inc | cpp/regex/match_results/dsc begin}}
+{{dsc inc|cpp/regex/match_results/dsc begin}}
-{{dsc inc | cpp/regex/match_results/dsc end}}
+{{dsc inc|cpp/regex/match_results/dsc end}}
-{{dsc h2 | Format}}
+{{dsc h2|Format}}
-{{dsc inc | cpp/regex/match_results/dsc format}}
+{{dsc inc|cpp/regex/match_results/dsc format}}
-{{dsc h2 | Modifiers}}
-{{dsc inc | cpp/regex/match_results/dsc swap}}
 {{dsc end}}
 ===Non-member functions===
 {{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}}
-[[de:cpp/regex/match results]]
+deesfritjakoptruzh
-[[es:cpp/regex/match results]]
-[[fr:cpp/regex/match results]]
-[[it:cpp/regex/match results]]
-[[ja:cpp/regex/match results]]
-[[ko:cpp/regex/match results]]
-[[pt:cpp/regex/match results]]
-[[ru:cpp/regex/match results]]
-[[zh:cpp/regex/match results]]

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Diagnostics library
Memory management library
Metaprogramming library (C++11)
General utilities library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
Technical specifications
Symbols index
External libraries

Classes
basic_regex (C++11)
sub_match (C++11)
match_results (C++11)
Algorithms
regex_match (C++11)
regex_search (C++11)
regex_replace (C++11)
Iterators
regex_iterator (C++11)
regex_token_iterator (C++11)
Exceptions
regex_error (C++11)
Traits
regex_traits (C++11)
Constants
syntax_option_type (C++11)
match_flag_type (C++11)
error_type (C++11)
Regex Grammar
Modified ECMAScript-262 (C++11)

Member functions
match_results::match_results
match_results::~match_results
match_results::operator=
match_results::get_allocator
State
match_results::ready
Element access
match_results::size
match_results::max_size
match_results::empty
match_results::length
match_results::position
match_results::str
match_results::operator[]
match_results::prefix
match_results::suffix
Iterators
match_results::beginmatch_results::cbegin
match_results::endmatch_results::cend
Format
match_results::format
Modifiers
match_results::swap
Non-member functions
operator==operator!= (until C++20)
swap(std::match_results)

cppreference.com

Namespaces

Variants

Views

Actions

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

Latest revision as of 07:15, 25 December 2023

Contents

[edit] Type requirements

[edit] Specializations

[edit] Member types

[edit] Member functions

State

Size

Element access

Iterators

Format

Modifiers

[edit] Non-member functions

Navigation

Toolbox