---
name: "std::match_results"
section: "3cxx"
platform: "linux"
package: "libstdc++-12-doc"
version: "12.4.0-5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/std::match_results/3cxx"
---

# std::match\_results(3cxx)

The results of a match or search operation.

## NAME

std::match\_results\< \_Bi\_iter, \_Alloc \> - The results of a match or search operation.

## SYNOPSIS

`#include <regex>`

Inherits **std::vector\< \_Tp, \_Alloc \>**.

### Public Types

**28.10 Public Types**\

**typedef** **sub\_match**\< \_Bi\_iter \> **value\_type**\
 **typedef** const **value\_type** & **const\_reference**\
 **typedef** **value\_type** & **reference**\
 **typedef** \_Base\_type::const\_iterator **const\_iterator**\
 **typedef** const\_iterator **iterator**\
 **typedef** \_\_iter\_traits::difference\_type **difference\_type**\
 **typedef** **allocator\_traits**\< \_Alloc \>::size\_type **size\_type**\
 **typedef** \_Alloc **allocator\_type**\
 **typedef** \_\_iter\_traits::value\_type **char\_type**\
 **typedef** **std::basic\_string**\< char\_type \> **string\_type**\

### Public Member Functions

bool **ready** () const noexcept\
 Indicates if the match\_results is ready.

**28.10.1 Construction, Copying, and Destruction**\

**match\_results** ()\
 Constructs a default match\_results container.  **match\_results** (const \_Alloc &\_\_a) noexcept\
 Constructs a default match\_results container.  **match\_results** (const **match\_results** &)=**default**\
 Copy constructs a match\_results.  **match\_results** (**match\_results** &&) noexcept=**default**\
 Move constructs a match\_results.  **match\_results** & **operator=** (const **match\_results** &)=**default**\
 Assigns rhs to \*this.  **match\_results** & **operator=** (**match\_results** &&)=**default**\
 Move-assigns rhs to \*this.  **~match\_results** ()=**default**\
 Destroys a match\_results object.  **match\_results** (const **match\_results** &**\_\_m**, const \_Alloc &\_\_a)\
 Constructs a default match\_results container.  **match\_results** (**match\_results** &&**\_\_m**, const \_Alloc &\_\_a) noexcept(noexcept(**\_Base\_type**(**std::move**(**\_\_m**), \_\_a)))\
 Constructs a default match\_results container.

**28.10.2 Size**\

size\_type **size** () const noexcept\
 Gets the number of matches and submatches.  size\_type **max\_size** () const noexcept\
 Gets the number of matches and submatches.  bool **empty** () const noexcept\
 Indicates if the match\_results contains no results.

**28.10.4 Element Access**\

difference\_type **length** (size\_type **\_\_sub**=0) const\
 Gets the length of the indicated submatch.  difference\_type **position** (size\_type **\_\_sub**=0) const\
 Gets the offset of the beginning of the indicated submatch.  **string\_type** **str** (size\_type **\_\_sub**=0) const\
 Gets the match or submatch converted to a string type.  **const\_reference** **operator\[\]** (size\_type **\_\_sub**) const\
 Gets a sub\_match reference for the match or submatch.  **const\_reference** **prefix** () const\
 Gets a sub\_match representing the match prefix.  **const\_reference** **suffix** () const\
 Gets a sub\_match representing the match suffix.  const\_iterator **begin** () const noexcept\
 Gets an iterator to the start of the sub\_match collection.  const\_iterator **cbegin** () const noexcept\
 Gets an iterator to the start of the sub\_match collection.  const\_iterator **end** () const noexcept\
 Gets an iterator to one-past-the-end of the collection.  const\_iterator **cend** () const noexcept\
 Gets an iterator to one-past-the-end of the collection.

**28.10.5 Formatting**\
 These functions perform formatted substitution of the matched character sequences into their target. The format specifiers and escape sequences accepted by these functions are determined by their `flags` parameter as documented above.

template\<**typename** **\_Out\_iter** \> **\_Out\_iter** **format** (**\_Out\_iter** **\_\_out**, const char\_type \***\_\_fmt\_first**, const char\_type \***\_\_fmt\_last**, **match\_flag\_type** \_\_flags=**regex\_constants::format\_default**) const\
 template\<**typename** **\_Out\_iter** , **typename** **\_St** , **typename** **\_Sa** \> **\_Out\_iter** **format** (**\_Out\_iter** **\_\_out**, const **basic\_string**\< char\_type, **\_St**, **\_Sa** \> &**\_\_fmt**, **match\_flag\_type** \_\_flags=**regex\_constants::format\_default**) const\
 template\<**typename** **\_St** , **typename** **\_Sa** \> **basic\_string**\< char\_type, **\_St**, **\_Sa** \> **format** (const **basic\_string**\< char\_type, **\_St**, **\_Sa** \> &**\_\_fmt**, **match\_flag\_type** \_\_flags=**regex\_constants::format\_default**) const\
 **string\_type** **format** (const char\_type \***\_\_fmt**, **match\_flag\_type** \_\_flags=**regex\_constants::format\_default**) const\

**28.10.6 Allocator**\

allocator\_type **get\_allocator** () const noexcept\
 Gets a copy of the allocator.

**28.10.7 Swap**\

**void** **swap** (**match\_results** &**\_\_that**) noexcept\
 Swaps the contents of two match\_results.

### Private Member Functions

constexpr iterator **begin** () noexcept\
 constexpr iterator **end** () noexcept\
 constexpr **const\_reference** **operator\[\]** (size\_type \_\_n) const noexcept\
 Subscript access to the data contained in the vector.  constexpr **reference** **operator\[\]** (size\_type \_\_n) noexcept\
 Subscript access to the data contained in the vector.  constexpr **void** **swap** (**vector** &\_\_x) noexcept\
 Swaps data with another vector.

### Friends

template\<**typename** , **typename** , **typename** \> **class** **regex\_iterator**\

### Related Symbols

(Note that these are not member symbols.)  template\<**typename** \_Bi\_iter , **class** \_Alloc \> bool **operator!=** (const **match\_results**\< \_Bi\_iter, \_Alloc \> &**\_\_m1**, const **match\_results**\< \_Bi\_iter, \_Alloc \> &**\_\_m2**)\
 Compares two match\_results for inequality.  template\<**typename** \_Bi\_iter , **typename** \_Alloc \> bool **operator==** (const **match\_results**\< \_Bi\_iter, \_Alloc \> &**\_\_m1**, const **match\_results**\< \_Bi\_iter, \_Alloc \> &**\_\_m2**)\
 Compares two match\_results for equality.  template\<**typename** \_Bi\_iter , **typename** \_Alloc \> **void** **swap** (**match\_results**\< \_Bi\_iter, \_Alloc \> &**\_\_lhs**, **match\_results**\< \_Bi\_iter, \_Alloc \> &**\_\_rhs**) noexcept\
 Swaps two match results.

## Detailed Description

### template\<typename \_Bi\_iter, typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\>

class std::match\_results\< \_Bi\_iter, \_Alloc \>"The results of a match or search operation.

A collection of character sequences representing the result of a regular expression match. Storage for the collection is allocated and freed as necessary by the member functions of class template match\_results.

This class satisfies the Sequence requirements, with the exception that only the operations defined for a const-qualified Sequence are supported.

The sub\_match object stored at index 0 represents sub-expression 0, i.e. the whole match. In this case the sub\_match member matched is always true. The sub\_match object stored at index n denotes what matched the marked sub-expression n within the matched expression. If the sub-expression n participated in a regular expression match then the sub\_match member matched evaluates to true, and members first and second denote the range of characters \[first, second) which formed that match. Otherwise matched is false, and members first and second point to the end of the sequence that was searched.

**Since**

C++11

## Constructor & Destructor Documentation

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> std::match\_results\< \_Bi\_iter, \_Alloc \>::match\_results ()` [inline]`

Constructs a default match\_results container.

**Postcondition**

size() returns 0 and str() returns an empty string.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> std::match\_results\< \_Bi\_iter, \_Alloc \>::match\_results (const \_Alloc & \_\_a)` [inline]`, ` [explicit]`, ` [noexcept]`

Constructs a default match\_results container.

**Postcondition**

size() returns 0 and str() returns an empty string.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> std::match\_results\< \_Bi\_iter, \_Alloc \>::match\_results (const match\_results\< \_Bi\_iter, \_Alloc \> &)` [default]`

Copy constructs a match\_results.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> std::match\_results\< \_Bi\_iter, \_Alloc \>::match\_results (match\_results\< \_Bi\_iter, \_Alloc \> &&)` [default]`, ` [noexcept]`

Move constructs a match\_results.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> std::match\_results\< \_Bi\_iter, \_Alloc \>::~match\_results ()` [default]`

Destroys a match\_results object.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> std::match\_results\< \_Bi\_iter, \_Alloc \>::match\_results (const match\_results\< \_Bi\_iter, \_Alloc \> & \_\_m, const \_Alloc & \_\_a)` [inline]`

Constructs a default match\_results container.

**Postcondition**

size() returns 0 and str() returns an empty string.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> std::match\_results\< \_Bi\_iter, \_Alloc \>::match\_results (match\_results\< \_Bi\_iter, \_Alloc \> && \_\_m, const \_Alloc & \_\_a)` [inline]`, ` [noexcept]`

Constructs a default match\_results container.

**Postcondition**

size() returns 0 and str() returns an empty string.

## Member Function Documentation

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> const\_iterator std::match\_results\< \_Bi\_iter, \_Alloc \>::begin () const` [inline]`, ` [noexcept]`

Gets an iterator to the start of the sub\_match collection.

Referenced by **std::match\_results\< \_Bi\_iter, \_Alloc \>::cbegin()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> const\_iterator std::match\_results\< \_Bi\_iter, \_Alloc \>::cbegin () const` [inline]`, ` [noexcept]`

Gets an iterator to the start of the sub\_match collection.

References **std::match\_results\< \_Bi\_iter, \_Alloc \>::begin()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> const\_iterator std::match\_results\< \_Bi\_iter, \_Alloc \>::cend () const` [inline]`, ` [noexcept]`

Gets an iterator to one-past-the-end of the collection.

References **std::match\_results\< \_Bi\_iter, \_Alloc \>::end()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> bool std::match\_results\< \_Bi\_iter, \_Alloc \>::empty () const` [inline]`, ` [noexcept]`

Indicates if the match\_results contains no results.

**Return values**

*true* The match\_results object is empty. \
 *false* The match\_results object is not empty.

Referenced by **std::match\_results\< \_Bi\_iter, \_Alloc \>::prefix()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::suffix()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> const\_iterator std::match\_results\< \_Bi\_iter, \_Alloc \>::end () const` [inline]`, ` [noexcept]`

Gets an iterator to one-past-the-end of the collection.

Referenced by **std::match\_results\< \_Bi\_iter, \_Alloc \>::cend()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> template\<typename \_Out\_iter , typename \_St , typename \_Sa \> \_Out\_iter std::match\_results\< \_Bi\_iter, \_Alloc \>::format (\_Out\_iter \_\_out, const basic\_string\< char\_type, \_St, \_Sa \> & \_\_fmt, match\_flag\_type \_\_flags = regex\_constants::format\_default) const` [inline]`

**Precondition**

ready() == true

References **std::match\_results\< \_Bi\_iter, \_Alloc \>::format()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> template\<typename \_Out\_iter \> \_Out\_iter std::match\_results\< \_Bi\_iter, \_Alloc \>::format (\_Out\_iter \_\_out, const char\_type \* \_\_fmt\_first, const char\_type \* \_\_fmt\_last, match\_flag\_type \_\_flags = regex\_constants::format\_default) const

**Precondition**

ready() == true

Referenced by **std::match\_results\< \_Bi\_iter, \_Alloc \>::format()**, **std::match\_results\< \_Bi\_iter, \_Alloc \>::format()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::format()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> template\<typename \_St , typename \_Sa \> basic\_string\< char\_type, \_St, \_Sa \> std::match\_results\< \_Bi\_iter, \_Alloc \>::format (const basic\_string\< char\_type, \_St, \_Sa \> & \_\_fmt, match\_flag\_type \_\_flags = regex\_constants::format\_default) const` [inline]`

**Precondition**

ready() == true

References **std::back\_inserter()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::format()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> string\_type std::match\_results\< \_Bi\_iter, \_Alloc \>::format (const char\_type \* \_\_fmt, match\_flag\_type \_\_flags = regex\_constants::format\_default) const` [inline]`

**Precondition**

ready() == true

References **std::back\_inserter()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::format()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> allocator\_type std::match\_results\< \_Bi\_iter, \_Alloc \>::get\_allocator () const` [inline]`, ` [noexcept]`

Gets a copy of the allocator.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> difference\_type std::match\_results\< \_Bi\_iter, \_Alloc \>::length (size\_type \_\_sub = `0`) const` [inline]`

Gets the length of the indicated submatch.

**Parameters**

*\_\_sub* indicates the submatch.

**Precondition**

ready() == true

This function returns the length of the indicated submatch, or the length of the entire match if `__sub` is zero (the default).

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> size\_type std::match\_results\< \_Bi\_iter, \_Alloc \>::max\_size () const` [inline]`, ` [noexcept]`

Gets the number of matches and submatches. The number of matches for a given regular expression will be either 0 if there was no match or mark\_count() + 1 if a match was successful. Some matches may be empty.

**Returns**

the number of matches found.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> match\_results & std::match\_results\< \_Bi\_iter, \_Alloc \>::operator= (const match\_results\< \_Bi\_iter, \_Alloc \> &)` [default]`

Assigns rhs to \*this.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> match\_results & std::match\_results\< \_Bi\_iter, \_Alloc \>::operator= (match\_results\< \_Bi\_iter, \_Alloc \> &&)` [default]`

Move-assigns rhs to \*this.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> const\_reference std::match\_results\< \_Bi\_iter, \_Alloc \>::operator\[\] (size\_type \_\_sub) const` [inline]`

Gets a sub\_match reference for the match or submatch.

**Parameters**

*\_\_sub* indicates the submatch.

**Precondition**

ready() == true

This function gets a reference to the indicated submatch, or the entire match if `__sub` is zero.

If `__sub` \>= size() then this function returns a sub\_match with a special value indicating no submatch.

References **std::match\_results\< \_Bi\_iter, \_Alloc \>::ready()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::size()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> difference\_type std::match\_results\< \_Bi\_iter, \_Alloc \>::position (size\_type \_\_sub = `0`) const` [inline]`

Gets the offset of the beginning of the indicated submatch.

**Parameters**

*\_\_sub* indicates the submatch.

**Precondition**

ready() == true

This function returns the offset from the beginning of the target sequence to the beginning of the submatch, unless the value of `__sub` is zero (the default), in which case this function returns the offset from the beginning of the target sequence to the beginning of the match.

References **std::distance()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> const\_reference std::match\_results\< \_Bi\_iter, \_Alloc \>::prefix () const` [inline]`

Gets a sub\_match representing the match prefix.

**Precondition**

ready() == true

This function gets a reference to a sub\_match object representing the part of the target range between the start of the target range and the start of the match.

References **std::match\_results\< \_Bi\_iter, \_Alloc \>::empty()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::ready()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> bool std::match\_results\< \_Bi\_iter, \_Alloc \>::ready () const` [inline]`, ` [noexcept]`

Indicates if the match\_results is ready.

**Return values**

*true* The object has a fully-established result state. \
 *false* The object is not ready.

Referenced by **std::match\_results\< \_Bi\_iter, \_Alloc \>::operator\[\]()**, **std::match\_results\< \_Bi\_iter, \_Alloc \>::prefix()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::suffix()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> size\_type std::match\_results\< \_Bi\_iter, \_Alloc \>::size () const` [inline]`, ` [noexcept]`

Gets the number of matches and submatches. The number of matches for a given regular expression will be either 0 if there was no match or mark\_count() + 1 if a match was successful. Some matches may be empty.

**Returns**

the number of matches found.

Referenced by **std::match\_results\< \_Bi\_iter, \_Alloc \>::operator\[\]()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> string\_type std::match\_results\< \_Bi\_iter, \_Alloc \>::str (size\_type \_\_sub = `0`) const` [inline]`

Gets the match or submatch converted to a string type.

**Parameters**

*\_\_sub* indicates the submatch.

**Precondition**

ready() == true

This function gets the submatch (or match, if `__sub` is zero) extracted from the target range and converted to the associated string type.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> const\_reference std::match\_results\< \_Bi\_iter, \_Alloc \>::suffix () const` [inline]`

Gets a sub\_match representing the match suffix.

**Precondition**

ready() == true

This function gets a reference to a sub\_match object representing the part of the target range between the end of the match and the end of the target range.

References **std::match\_results\< \_Bi\_iter, \_Alloc \>::empty()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::ready()**.

### template\<typename \_Bi\_iter , typename \_Alloc = allocator\<sub\_match\<\_Bi\_iter\> \>\> void std::match\_results\< \_Bi\_iter, \_Alloc \>::swap (match\_results\< \_Bi\_iter, \_Alloc \> & \_\_that)` [inline]`, ` [noexcept]`

Swaps the contents of two match\_results.

References **std::swap()**, and **std::match\_results\< \_Bi\_iter, \_Alloc \>::swap()**.

Referenced by **std::match\_results\< \_Bi\_iter, \_Alloc \>::swap()**.

## Author

Generated automatically by Doxygen for libstdc++ from the source code.