---
name: "std::sub_match"
section: "3"
platform: "linux"
package: "gcc"
version: "16.2.1+r23+gd564253eb6c8-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/std::sub_match"
---

# std::sub\_match(3)

## 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\> auto **operator\<=\>** (const sub\_match\< \_BiIter \> &\_\_lhs, const sub\_match\< \_BiIter \> &\_\_rhs) noexcept(\_\_detail::\_\_is\_contiguous\_iter\< \_BiIter \>::value)\
 Three-way comparison of two regular expression submatches.  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 \_Alloc\> auto **operator\<=\>** (const sub\_match\< \_Bi\_iter \> &\_\_lhs, const \_\_sub\_match\_string\< \_Bi\_iter, \_Ch\_traits, \_Alloc \> &\_\_rhs) noexcept(\_\_detail::\_\_is\_contiguous\_iter\< \_Bi\_iter \>::value)\
 Three-way comparison 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 equivalence of a regular expression submatch and a C string.  template\<typename \_Bi\_iter\> auto **operator\<=\>** (const sub\_match\< \_Bi\_iter \> &\_\_lhs, typename **iterator\_traits**\< \_Bi\_iter \>::value\_type const \*\_\_rhs) noexcept(\_\_detail::\_\_is\_contiguous\_iter\< \_Bi\_iter \>::value)\
 Three-way comparison 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 equivalence of a regular expression submatch and a character.  template\<typename \_Bi\_iter\> auto **operator\<=\>** (const sub\_match\< \_Bi\_iter \> &\_\_lhs, typename **iterator\_traits**\< \_Bi\_iter \>::value\_type const &\_\_rhs) noexcept(\_\_detail::\_\_is\_contiguous\_iter\< \_Bi\_iter \>::value)\
 Three-way comparison 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.

Referenced by **std::sub\_match\< const char \* \>::operator==()**, and **std::sub\_match\< const char \* \>::operator==()**.

### 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.

### 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.

### 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\< const char \* \>::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.

## Author

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