QRegularExpressionMatch Class

Member Function Documentation

QRegularExpressionMatch::QRegularExpressionMatch()

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.

QRegularExpressionMatch::QRegularExpressionMatch(const QRegularExpressionMatch &match)

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

See also operator=().

[noexcept, since 6.1] QRegularExpressionMatch::QRegularExpressionMatch(QRegularExpressionMatch &&match)

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.

This function was introduced in Qt 6.1.

See also operator=().

[noexcept] QRegularExpressionMatch::~QRegularExpressionMatch()

Destroys the match result.

QString QRegularExpressionMatch::captured(QAnyStringView name) const

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.

See also capturedView(), capturedStart(), capturedEnd(), capturedLength(), and QString::isNull().

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.

See also capturedView(), lastCapturedIndex(), capturedStart(), capturedEnd(), capturedLength(), and QString::isNull().

qsizetype QRegularExpressionMatch::capturedEnd(QAnyStringView name) const

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.

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

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(), and captured().

qsizetype QRegularExpressionMatch::capturedLength(QAnyStringView name) const

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

See also capturedStart(), capturedEnd(), and captured().

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

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

See also capturedStart(), capturedEnd(), and captured().

qsizetype QRegularExpressionMatch::capturedStart(QAnyStringView name) const

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.

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

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(), and captured().

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.

QStringView QRegularExpressionMatch::capturedView(QAnyStringView name) const

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.

See also captured(), capturedStart(), capturedEnd(), capturedLength(), and QStringView::isNull().

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

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.

See also captured(), lastCapturedIndex(), capturedStart(), capturedEnd(), capturedLength(), and QStringView::isNull().

[since 6.3] bool QRegularExpressionMatch::hasCaptured(QAnyStringView name) const

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

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.

This function was introduced in Qt 6.3.

See also captured() and hasMatch().

[since 6.3] bool QRegularExpressionMatch::hasCaptured(int nth) const

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

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.

This function was introduced in Qt 6.3.

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

bool QRegularExpressionMatch::hasMatch() const

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

See also QRegularExpression::match() and hasPartialMatch().

bool QRegularExpressionMatch::hasPartialMatch() const

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

See also QRegularExpression::match(), QRegularExpression::MatchType, and hasMatch().

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() and QRegularExpression::isValid().

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(), and capturedLength().

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(), and 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(), and matchOptions().

QRegularExpression QRegularExpressionMatch::regularExpression() const

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

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

[noexcept] void QRegularExpressionMatch::swap(QRegularExpressionMatch &other)

Swaps this match result with other. This operation is very fast and never fails.

[noexcept] QRegularExpressionMatch &QRegularExpressionMatch::operator=(QRegularExpressionMatch &&match)

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.

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

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