Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QRegularExpressionMatch Class Reference

\inmodule QtCore \reentrant More...

#include <qregularexpression.h>

Collaboration diagram for QRegularExpressionMatch:

Public Member Functions

 QRegularExpressionMatch ()
 ~QRegularExpressionMatch ()
 Destroys the match result.
 QRegularExpressionMatch (const QRegularExpressionMatch &match)
 Constructs a match result by copying the result of the given match.
 QRegularExpressionMatch (QRegularExpressionMatch &&match)=default
QRegularExpressionMatch & operator= (const QRegularExpressionMatch &match)
 Assigns the match result match to this object, and returns a reference to the copy.
QRegularExpressionMatch & operator= (QRegularExpressionMatch &&match) noexcept
 Move-assigns the match result match to this object, and returns a reference to the result.
void swap (QRegularExpressionMatch &other) noexcept
 \memberswap{match result}
QRegularExpression regularExpression () const
 Returns the QRegularExpression object whose match() function returned this object.
QRegularExpression::MatchType matchType () const
 Returns the match type that was used to get this QRegularExpressionMatch object, that is, the match type that was passed to QRegularExpression::match() or QRegularExpression::globalMatch().
QRegularExpression::MatchOptions matchOptions () const
 Returns the match options that were used to get this QRegularExpressionMatch object, that is, the match options that were passed to QRegularExpression::match() or QRegularExpression::globalMatch().
bool hasMatch () const
 Returns true if the regular expression matched against the subject string, or false otherwise.
bool hasPartialMatch () const
 Returns true if the regular expression partially matched against the subject string, or false otherwise.
bool isValid () const
 Returns true if the match object was obtained as a result from the QRegularExpression::match() function invoked on a valid QRegularExpression object; returns false if the QRegularExpression was invalid.
int lastCapturedIndex () const
 Returns the index of the last capturing group that captured something, including the implicit capturing group 0.
bool hasCaptured (QAnyStringView name) const
bool hasCaptured (int nth) const
QString captured (int nth=0) const
 Returns the substring captured by the nth capturing group.
QStringView capturedView (int nth=0) const
QString captured (QAnyStringView name) const
QStringView capturedView (QAnyStringView name) const
QStringList capturedTexts () const
 Returns a list of all strings captured by capturing groups, in the order the groups themselves appear in the pattern string.
qsizetype capturedStart (int nth=0) const
 Returns the offset inside the subject string corresponding to the starting position of the substring captured by the nth capturing group.
qsizetype capturedLength (int nth=0) const
 Returns the length of the substring captured by the nth capturing group.
qsizetype capturedEnd (int nth=0) const
 Returns the offset inside the subject string immediately after the ending position of the substring captured by the nth capturing group.
qsizetype capturedStart (QAnyStringView name) const
qsizetype capturedLength (QAnyStringView name) const
qsizetype capturedEnd (QAnyStringView name) const

Friends

class QRegularExpression
struct QRegularExpressionMatchPrivate
class QRegularExpressionMatchIterator

(Note that these are not member symbols.)

QDebug operator<< (QDebug debug, const QRegularExpressionMatch &match)
 Writes the match object match into the debug object debug for debugging purposes.

Detailed Description

\inmodule QtCore \reentrant

The QRegularExpressionMatch class provides the results of a matching a QRegularExpression against a string.

Since
5.0

\keyword regular expression match

A QRegularExpressionMatch object can be obtained by calling the QRegularExpression::match() function, or as a single result of a global match from a QRegularExpressionMatchIterator.

The success or the failure of a match attempt can be inspected by calling the hasMatch() function. QRegularExpressionMatch also reports a successful partial match through the hasPartialMatch() function.

In addition, QRegularExpressionMatch returns the substrings captured by the capturing groups in the pattern string. The implicit capturing group with index 0 captures the result of the whole match. The captured() function returns each substring captured, either by the capturing group's index or by its name:

QRegularExpression re("(\\d\\d) (?<name>\\w+)");
QRegularExpressionMatch match = re.match("23 Jordan");
if (match.hasMatch()) {
QString number = match.captured(1); // first == "23"
QString name = match.captured("name"); // name == "Jordan"
}

For each captured substring it is possible to query its starting and ending offsets in the subject string by calling the capturedStart() and the capturedEnd() function, respectively. The length of each captured substring is available using the capturedLength() function.

The convenience function capturedTexts() will return {all} the captured substrings at once (including the substring matched by the entire pattern) in the order they have been captured by capturing groups; that is, {captured(i) == capturedTexts().at(i)}.

You can retrieve the QRegularExpression object the subject string was matched against by calling the regularExpression() function; the match type and the match options are available as well by calling the matchType() and the matchOptions() respectively.

Please refer to the QRegularExpression documentation for more information about the Qt regular expression classes.

See also
QRegularExpression

Definition at line 198 of file qregularexpression.h.

Constructor & Destructor Documentation

◆ QRegularExpressionMatch() [1/3]

QRegularExpressionMatch::QRegularExpressionMatch ( )
Since
5.1

Constructs a valid, empty QRegularExpressionMatch object. The regular expression is set to a default-constructed one; the match type to QRegularExpression::NoMatch and the match options to QRegularExpression::NoMatchOption.

The object will report no match through the hasMatch() and the hasPartialMatch() member functions.

Definition at line 2097 of file qregularexpression.cpp.

◆ ~QRegularExpressionMatch()

QRegularExpressionMatch::~QRegularExpressionMatch ( )

Destroys the match result.

Definition at line 2110 of file qregularexpression.cpp.

◆ QRegularExpressionMatch() [2/3]

QRegularExpressionMatch::QRegularExpressionMatch ( const QRegularExpressionMatch & match)

Constructs a match result by copying the result of the given match.

See also
operator=()

Definition at line 2121 of file qregularexpression.cpp.

◆ QRegularExpressionMatch() [3/3]

QRegularExpressionMatch::QRegularExpressionMatch ( QRegularExpressionMatch && match)
default
Since
6.1

Constructs a match result by moving the result from the given match.

Note that a moved-from QRegularExpressionMatch can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

See also
operator=()

Member Function Documentation

◆ captured() [1/2]

QString QRegularExpressionMatch::captured ( int nth = 0) const

Returns the substring captured by the nth capturing group.

If the nth capturing group did not capture a string, or if there is no such capturing group, returns a null QString.

Note
The implicit capturing group number 0 captures the substring matched by the entire pattern.
See also
capturedView(), lastCapturedIndex(), capturedStart(), capturedEnd(), capturedLength(), QString::isNull()

Definition at line 2300 of file qregularexpression.cpp.

◆ captured() [2/2]

QString QRegularExpressionMatch::captured ( QAnyStringView name) const
Since
5.10

Returns the substring captured by the capturing group named name.

If the named capturing group name did not capture a string, or if there is no capturing group named name, returns a null QString.

Note
In Qt versions prior to 6.8, this function took QString or QStringView, not QAnyStringView.
See also
capturedView(), capturedStart(), capturedEnd(), capturedLength(), QString::isNull()

Definition at line 2346 of file qregularexpression.cpp.

◆ capturedEnd() [1/2]

qsizetype QRegularExpressionMatch::capturedEnd ( int nth = 0) const

Returns the offset inside the subject string immediately after the ending position of the substring captured by the nth capturing group.

If the nth capturing group did not capture a string or doesn't exist, returns -1.

See also
capturedStart(), capturedLength(), captured()

Definition at line 2435 of file qregularexpression.cpp.

◆ capturedEnd() [2/2]

qsizetype QRegularExpressionMatch::capturedEnd ( QAnyStringView name) const
Since
5.10

Returns the offset inside the subject string immediately after the ending position of the substring captured by the capturing group named name. If the capturing group named name did not capture a string or doesn't exist, returns -1.

Note
In Qt versions prior to 6.8, this function took QString or QStringView, not QAnyStringView.
See also
capturedStart(), capturedLength(), captured()

Definition at line 2507 of file qregularexpression.cpp.

◆ capturedLength() [1/2]

qsizetype QRegularExpressionMatch::capturedLength ( int nth = 0) const

Returns the length of the substring captured by the nth capturing group.

Note
This function returns 0 if the nth capturing group did not capture a string or doesn't exist.
See also
capturedStart(), capturedEnd(), captured()

Definition at line 2422 of file qregularexpression.cpp.

◆ capturedLength() [2/2]

qsizetype QRegularExpressionMatch::capturedLength ( QAnyStringView name) const
Since
5.10

Returns the length of the substring captured by the capturing group named name.

Note
This function returns 0 if the capturing group named name did not capture a string or doesn't exist.
In Qt versions prior to 6.8, this function took QString or QStringView, not QAnyStringView.
See also
capturedStart(), capturedEnd(), captured()

Definition at line 2482 of file qregularexpression.cpp.

◆ capturedStart() [1/2]

qsizetype QRegularExpressionMatch::capturedStart ( int nth = 0) const

Returns the offset inside the subject string corresponding to the starting position of the substring captured by the nth capturing group.

If the nth capturing group did not capture a string or doesn't exist, returns -1.

See also
capturedEnd(), capturedLength(), captured()

Definition at line 2406 of file qregularexpression.cpp.

◆ capturedStart() [2/2]

qsizetype QRegularExpressionMatch::capturedStart ( QAnyStringView name) const
Since
5.10

Returns the offset inside the subject string corresponding to the starting position of the substring captured by the capturing group named name. If the capturing group named name did not capture a string or doesn't exist, returns -1.

Note
In Qt versions prior to 6.8, this function took QString or QStringView, not QAnyStringView.
See also
capturedEnd(), capturedLength(), captured()

Definition at line 2456 of file qregularexpression.cpp.

◆ capturedTexts()

QStringList QRegularExpressionMatch::capturedTexts ( ) const

Returns a list of all strings captured by capturing groups, in the order the groups themselves appear in the pattern string.

The list includes the implicit capturing group number 0, capturing the substring matched by the entire pattern.

Definition at line 2389 of file qregularexpression.cpp.

◆ capturedView() [1/2]

QStringView QRegularExpressionMatch::capturedView ( int nth = 0) const
Since
5.10

Returns a view of the substring captured by the nth capturing group.

If the nth capturing group did not capture a string, or if there is no such capturing group, returns a null QStringView.

Note
The implicit capturing group number 0 captures the substring matched by the entire pattern.
See also
captured(), lastCapturedIndex(), capturedStart(), capturedEnd(), capturedLength(), QStringView::isNull()

Definition at line 2319 of file qregularexpression.cpp.

◆ capturedView() [2/2]

QStringView QRegularExpressionMatch::capturedView ( QAnyStringView name) const
Since
5.10

Returns a view of the string captured by the capturing group named name.

If the named capturing group name did not capture a string, or if there is no capturing group named name, returns a null QStringView.

Note
In Qt versions prior to 6.8, this function took QString or QStringView, not QAnyStringView.
See also
captured(), capturedStart(), capturedEnd(), capturedLength(), QStringView::isNull()

Definition at line 2371 of file qregularexpression.cpp.

◆ hasCaptured() [1/2]

bool QRegularExpressionMatch::hasCaptured ( int nth) const
Since
6.3

Returns true if the nth capturing group captured something in the subject string, and false otherwise (or if there is no such capturing group).

Note
The implicit capturing group number 0 captures the substring matched by the entire pattern.
Some capturing groups in a regular expression may not have captured anything even if the regular expression matched. This may happen, for instance, if a conditional operator is used in the pattern:
QRegularExpression re("([a-z]+)|([A-Z]+)");
QRegularExpressionMatch m = re.match("UPPERCASE");
if (m.hasMatch()) {
qDebug() << m.hasCaptured(0); // true
qDebug() << m.hasCaptured(1); // false
qDebug() << m.hasCaptured(2); // true
}

Similarly, a capturing group may capture a substring of length 0; this function will return {true} for such a capturing group.

See also
captured(), lastCapturedIndex(), hasMatch()

Definition at line 2280 of file qregularexpression.cpp.

◆ hasCaptured() [2/2]

bool QRegularExpressionMatch::hasCaptured ( QAnyStringView name) const
Since
6.3

Returns true if the capturing group named name captured something in the subject string, and false otherwise (or if there is no capturing group called name).

Note
Some capturing groups in a regular expression may not have captured anything even if the regular expression matched. This may happen, for instance, if a conditional operator is used in the pattern:
QRegularExpression re("([a-z]+)|([A-Z]+)");
QRegularExpressionMatch m = re.match("UPPERCASE");
if (m.hasMatch()) {
qDebug() << m.hasCaptured(0); // true
qDebug() << m.hasCaptured(1); // false
qDebug() << m.hasCaptured(2); // true
}

Similarly, a capturing group may capture a substring of length 0; this function will return {true} for such a capturing group.

Note
In Qt versions prior to 6.8, this function took QString or QStringView, not QAnyStringView.
See also
captured(), hasMatch()

Definition at line 2252 of file qregularexpression.cpp.

◆ hasMatch()

bool QRegularExpressionMatch::hasMatch ( ) const

Returns true if the regular expression matched against the subject string, or false otherwise.

See also
QRegularExpression::match(), hasPartialMatch()

Definition at line 2525 of file qregularexpression.cpp.

◆ hasPartialMatch()

bool QRegularExpressionMatch::hasPartialMatch ( ) const

Returns true if the regular expression partially matched against the subject string, or false otherwise.

Note
Only a match that explicitly used the one of the partial match types can yield a partial match. Still, if such a match succeeds totally, this function will return false, while hasMatch() will return true.
See also
QRegularExpression::match(), QRegularExpression::MatchType, hasMatch()

Definition at line 2540 of file qregularexpression.cpp.

◆ isValid()

bool QRegularExpressionMatch::isValid ( ) const

Returns true if the match object was obtained as a result from the QRegularExpression::match() function invoked on a valid QRegularExpression object; returns false if the QRegularExpression was invalid.

See also
QRegularExpression::match(), QRegularExpression::isValid()

Definition at line 2552 of file qregularexpression.cpp.

◆ lastCapturedIndex()

int QRegularExpressionMatch::lastCapturedIndex ( ) const

Returns the index of the last capturing group that captured something, including the implicit capturing group 0.

This can be used to extract all the substrings that were captured:

QRegularExpressionMatch match = re.match(string);
for (int i = 0; i <= match.lastCapturedIndex(); ++i) {
QString captured = match.captured(i);
// ...
}

Note that some of the capturing groups with an index less than lastCapturedIndex() could have not matched, and therefore captured nothing.

If the regular expression did not match, this function returns -1.

See also
hasCaptured(), captured(), capturedStart(), capturedEnd(), capturedLength()

Definition at line 2224 of file qregularexpression.cpp.

◆ matchOptions()

QRegularExpression::MatchOptions QRegularExpressionMatch::matchOptions ( ) const

Returns the match options that were used to get this QRegularExpressionMatch object, that is, the match options that were passed to QRegularExpression::match() or QRegularExpression::globalMatch().

See also
QRegularExpression::match(), regularExpression(), matchType()

Definition at line 2205 of file qregularexpression.cpp.

◆ matchType()

QRegularExpression::MatchType QRegularExpressionMatch::matchType ( ) const

Returns the match type that was used to get this QRegularExpressionMatch object, that is, the match type that was passed to QRegularExpression::match() or QRegularExpression::globalMatch().

See also
QRegularExpression::match(), regularExpression(), matchOptions()

Definition at line 2193 of file qregularexpression.cpp.

◆ operator=() [1/2]

QRegularExpressionMatch & QRegularExpressionMatch::operator= ( const QRegularExpressionMatch & match)

Assigns the match result match to this object, and returns a reference to the copy.

Definition at line 2144 of file qregularexpression.cpp.

◆ operator=() [2/2]

QRegularExpressionMatch & QRegularExpressionMatch::operator= ( QRegularExpressionMatch && match)
inlinenoexcept

Move-assigns the match result match to this object, and returns a reference to the result.

Note that a moved-from QRegularExpressionMatch can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.

Definition at line 206 of file qregularexpression.h.

◆ regularExpression()

QRegularExpression QRegularExpressionMatch::regularExpression ( ) const

Returns the QRegularExpression object whose match() function returned this object.

See also
QRegularExpression::match(), matchType(), matchOptions()

Definition at line 2180 of file qregularexpression.cpp.

◆ swap()

void QRegularExpressionMatch::swap ( QRegularExpressionMatch & other)
inlinenoexcept

\memberswap{match result}

Definition at line 208 of file qregularexpression.h.

◆ operator<<()

QDebug operator<< ( QDebug debug,
const QRegularExpressionMatch & match )
related

Writes the match object match into the debug object debug for debugging purposes.

See also
{Debugging Techniques}

Definition at line 2842 of file qregularexpression.cpp.

◆ QRegularExpression

friend class QRegularExpression
friend

Definition at line 265 of file qregularexpression.h.

◆ QRegularExpressionMatchIterator

friend class QRegularExpressionMatchIterator
friend

Definition at line 267 of file qregularexpression.h.

◆ QRegularExpressionMatchPrivate

friend struct QRegularExpressionMatchPrivate
friend

Definition at line 266 of file qregularexpression.h.

The documentation for this class was generated from the following files: