---
name: "std::sub_match"
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::sub_match/3cxx"
---

# std::sub\_match(3cxx)

## NAME

std::sub\_match\< \_BiIter \>

## SYNOPSIS

`#include <regex>`

### Public Types

**typedef** \_\_iter\_traits::difference\_type **difference\_type**\
 **typedef** \_BiIter **iterator**\
 **typedef** **basic\_string**\< value\_type \> **string\_type**\
 **typedef** \_\_iter\_traits::value\_type **value\_type**\

### Public Member Functions

int **compare** (const **sub\_match** &**\_\_s**) const\
 Compares this and another matched sequence.  difference\_type **length** () const noexcept\
 Gets the length of the matching sequence.  **operator string\_type** () const\
 Gets the matching sequence as a string.  **string\_type** **str** () const\
 Gets the matching sequence as a string.  **void** **swap** (**sub\_match** &**\_\_s**) noexcept(**\_\_is\_nothrow\_swappable**\< \_BiIter \>::value)\
 Swap the values of two sub\_match objects.

int **compare** (const **string\_type** &**\_\_s**) const\
 Compares this `sub_match` to a string.  int **compare** (const value\_type \***\_\_s**) const\
 Compares this `sub_match` to a string.

### Public Attributes

iterator **first**\
 bool **matched**\
 iterator **second**\

### Related Symbols

(Note that these are not member symbols.)

template\<**typename** \_BiIter \> bool **operator==** (const **sub\_match**\< \_BiIter \> &**\_\_lhs**, const **sub\_match**\< \_BiIter \> &**\_\_rhs**)\
 Tests the equivalence of two regular expression submatches.  template\<**typename** \_BiIter \> bool **operator!=** (const **sub\_match**\< \_BiIter \> &**\_\_lhs**, const **sub\_match**\< \_BiIter \> &**\_\_rhs**)\
 Tests the inequivalence of two regular expression submatches.  template\<**typename** \_BiIter \> bool **operator\<** (const **sub\_match**\< \_BiIter \> &**\_\_lhs**, const **sub\_match**\< \_BiIter \> &**\_\_rhs**)\
 Tests the ordering of two regular expression submatches.  template\<**typename** \_BiIter \> bool **operator\<=** (const **sub\_match**\< \_BiIter \> &**\_\_lhs**, const **sub\_match**\< \_BiIter \> &**\_\_rhs**)\
 Tests the ordering of two regular expression submatches.  template\<**typename** \_BiIter \> bool **operator\>=** (const **sub\_match**\< \_BiIter \> &**\_\_lhs**, const **sub\_match**\< \_BiIter \> &**\_\_rhs**)\
 Tests the ordering of two regular expression submatches.  template\<**typename** \_BiIter \> bool **operator\>** (const **sub\_match**\< \_BiIter \> &**\_\_lhs**, const **sub\_match**\< \_BiIter \> &**\_\_rhs**)\
 Tests the ordering of two regular expression submatches.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator==** (const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the equivalence of a string and a regular expression submatch.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator!=** (const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the inequivalence of a string and a regular expression submatch.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\<** (const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a string and a regular expression submatch.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\>** (const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a string and a regular expression submatch.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\>=** (const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a string and a regular expression submatch.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\<=** (const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a string and a regular expression submatch.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator==** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_rhs**)\
 Tests the equivalence of a regular expression submatch and a string.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator!=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_rhs**)\
 Tests the inequivalence of a regular expression submatch and a string.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\<** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a string.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\>** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a string.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\>=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a string.  template\<**typename** \_Bi\_iter , **typename** **\_Ch\_traits** , **typename** **\_Ch\_alloc** \> bool **operator\<=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, const **\_\_sub\_match\_string**\< \_Bi\_iter, **\_Ch\_traits**, **\_Ch\_alloc** \> &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a string.  template\<**typename** \_Bi\_iter \> bool **operator==** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the equivalence of a C string and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator!=** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the inequivalence of a C string and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\<** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a C string and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\>** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a C string and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\>=** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a C string and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\<=** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a C string and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator==** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_rhs**)\
 Tests the equivalence of a regular expression submatch and a C string.  template\<**typename** \_Bi\_iter \> bool **operator!=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_rhs**)\
 Tests the inequivalence of a regular expression submatch and a string.  template\<**typename** \_Bi\_iter \> bool **operator\<** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a C string.  template\<**typename** \_Bi\_iter \> bool **operator\>** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a C string.  template\<**typename** \_Bi\_iter \> bool **operator\>=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a C string.  template\<**typename** \_Bi\_iter \> bool **operator\<=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const \***\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a C string.  template\<**typename** \_Bi\_iter \> bool **operator==** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the equivalence of a character and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator!=** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the inequivalence of a character and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\<** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a character and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\>** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a character and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\>=** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a character and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator\<=** (**typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_lhs**, const **sub\_match**\< \_Bi\_iter \> &**\_\_rhs**)\
 Tests the ordering of a character and a regular expression submatch.  template\<**typename** \_Bi\_iter \> bool **operator==** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_rhs**)\
 Tests the equivalence of a regular expression submatch and a character.  template\<**typename** \_Bi\_iter \> bool **operator!=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_rhs**)\
 Tests the inequivalence of a regular expression submatch and a character.  template\<**typename** \_Bi\_iter \> bool **operator\<** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a character.  template\<**typename** \_Bi\_iter \> bool **operator\>** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a character.  template\<**typename** \_Bi\_iter \> bool **operator\>=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a character.  template\<**typename** \_Bi\_iter \> bool **operator\<=** (const **sub\_match**\< \_Bi\_iter \> &**\_\_lhs**, **typename** **iterator\_traits**\< \_Bi\_iter \>::value\_type const &**\_\_rhs**)\
 Tests the ordering of a regular expression submatch and a character.  template\<**typename** **\_Ch\_type** , **typename** **\_Ch\_traits** , **typename** \_Bi\_iter \> **basic\_ostream**\< **\_Ch\_type**, **\_Ch\_traits** \> & **operator\<\<** (**basic\_ostream**\< **\_Ch\_type**, **\_Ch\_traits** \> &**\_\_os**, const **sub\_match**\< \_Bi\_iter \> &**\_\_m**)\
 Inserts a matched string into an output stream.

## Detailed Description

### template\<typename \_BiIter\>

class std::sub\_match\< \_BiIter \>"A sequence of characters matched by a particular marked sub-expression.

An object of this class is essentially a pair of iterators marking a matched subexpression within a regular expression pattern match. Such objects can be converted to and compared with std::basic\_string objects of the same character type as the pattern matched by the regular expression.

A `sub_match<Iter>` has a public base class of type `pair<Iter, Iter>`, so inherits pair's data members named `first` and `second`. The iterators that make up the pair are the usual half-open interval referencing the actual original pattern matched.

**Since**

C++11

## Member Function Documentation

### template\<typename \_BiIter \> int std::sub\_match\< \_BiIter \>::compare (const string\_type & \_\_s) const` [inline]`

Compares this `sub_match` to a string.

**Parameters**

*\_\_s* A string to compare to this `sub_match`.

**Return values**

*negative* This matched sequence will collate before `__s`. \
 *zero* This matched sequence is equivalent to `__s`. \
 *positive* This matched sequence will collate after `__s`.

### template\<typename \_BiIter \> int std::sub\_match\< \_BiIter \>::compare (const sub\_match\< \_BiIter \> & \_\_s) const` [inline]`

Compares this and another matched sequence.

**Parameters**

*\_\_s* Another matched sequence to compare to this one.

**Return values**

*negative* This matched sequence will collate before `__s`. \
 *zero* This matched sequence is equivalent to `__s`. \
 *positive* This matched sequence will collate after `__s`.

### template\<typename \_BiIter \> int std::sub\_match\< \_BiIter \>::compare (const value\_type \* \_\_s) const` [inline]`

Compares this `sub_match` to a string.

**Parameters**

*\_\_s* A string to compare to this `sub_match`.

**Return values**

*negative* This matched sequence will collate before `__s`. \
 *zero* This matched sequence is equivalent to `__s`. \
 *positive* This matched sequence will collate after `__s`.

### template\<typename \_BiIter \> difference\_type std::sub\_match\< \_BiIter \>::length () const` [inline]`, ` [noexcept]`

Gets the length of the matching sequence.

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

### template\<typename \_BiIter \> std::sub\_match\< \_BiIter \>::operator string\_type () const` [inline]`

Gets the matching sequence as a string.

**Returns**

the matching sequence as a string.

This is the implicit conversion operator. It is identical to the str() member function except that it will want to pop up in unexpected places and cause a great deal of confusion and cursing from the unwary.

References **std::sub\_match\< \_BiIter \>::str()**.

### template\<typename \_BiIter \> string\_type std::sub\_match\< \_BiIter \>::str () const` [inline]`

Gets the matching sequence as a string.

**Returns**

the matching sequence as a string.

Referenced by **std::sub\_match\< \_BiIter \>::operator string\_type()**.

### template\<typename \_BiIter \> void std::sub\_match\< \_BiIter \>::swap (sub\_match\< \_BiIter \> & \_\_s)` [inline]`, ` [noexcept]`

Swap the values of two sub\_match objects.

References **std::swap()**, and **std::pair\< \_T1, \_T2 \>::swap()**.

## Author

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