QRegularExpressionMatch Class

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

Header: #include <QRegularExpressionMatch>
qmake: QT += core
Since: Qt 5.0

This class was introduced in Qt 5.0.

Note: All functions in this class are reentrant.

Public Functions

QRegularExpressionMatch(const QRegularExpressionMatch &match)
QRegularExpressionMatch()
QRegularExpressionMatch &operator=(QRegularExpressionMatch &&match)
QRegularExpressionMatch &operator=(const QRegularExpressionMatch &match)
~QRegularExpressionMatch()
QString captured(int nth = 0) const
QString captured(const QString &name) const
QString captured(QStringView name) const
int capturedEnd(int nth = 0) const
int capturedEnd(const QString &name) const
int capturedEnd(QStringView name) const
int capturedLength(int nth = 0) const
int capturedLength(const QString &name) const
int capturedLength(QStringView name) const
QStringRef capturedRef(int nth = 0) const
QStringRef capturedRef(const QString &name) const
QStringRef capturedRef(QStringView name) const
int capturedStart(int nth = 0) const
int capturedStart(const QString &name) const
int capturedStart(QStringView name) const
QStringList capturedTexts() const
QStringView capturedView(int nth = 0) const
QStringView capturedView(QStringView name) const
bool hasMatch() const
bool hasPartialMatch() const
bool isValid() const
int lastCapturedIndex() const
QRegularExpression::MatchOptions matchOptions() const
QRegularExpression::MatchType matchType() const
QRegularExpression regularExpression() const
void swap(QRegularExpressionMatch &other)
QDebug operator<<(QDebug debug, const QRegularExpressionMatch &match)

Detailed Description

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.

Member Function Documentation

QRegularExpressionMatch::QRegularExpressionMatch(const QRegularExpressionMatch &match)

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

See also operator=().

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.

This function was introduced in Qt 5.1.

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

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

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

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

QRegularExpressionMatch::~QRegularExpressionMatch()

Destroys the match result.

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 capturedRef(), capturedView(), lastCapturedIndex(), capturedStart(), capturedEnd(), capturedLength(), and QString::isNull().

QString QRegularExpressionMatch::captured(const QString &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 capturedRef(), capturedView(), capturedStart(), capturedEnd(), capturedLength(), and QString::isNull().

QString QRegularExpressionMatch::captured(QStringView 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.

This function was introduced in Qt 5.10.

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

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

int QRegularExpressionMatch::capturedEnd(const QString &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().

int QRegularExpressionMatch::capturedEnd(QStringView 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.

This function was introduced in Qt 5.10.

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

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

int QRegularExpressionMatch::capturedLength(const QString &name) const

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.

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

int QRegularExpressionMatch::capturedLength(QStringView name) const

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.

This function was introduced in Qt 5.10.

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

QStringRef QRegularExpressionMatch::capturedRef(int nth = 0) const

Returns a reference to 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 QStringRef.

Note: The implicit capturing group number 0 captures the substring matched by the entire pattern.

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

QStringRef QRegularExpressionMatch::capturedRef(const QString &name) const

Returns a reference to 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 QStringRef.

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

QStringRef QRegularExpressionMatch::capturedRef(QStringView name) const

Returns a reference to 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 QStringRef.

This function was introduced in Qt 5.10.

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

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

int QRegularExpressionMatch::capturedStart(const QString &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().

int QRegularExpressionMatch::capturedStart(QStringView 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.

This function was introduced in Qt 5.10.

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

Note: The implicit capturing group number 0 captures the substring matched by the entire pattern.

This function was introduced in Qt 5.10.

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

QStringView QRegularExpressionMatch::capturedView(QStringView 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.

This function was introduced in Qt 5.10.

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

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.

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

void QRegularExpressionMatch::swap(QRegularExpressionMatch &other)

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

Related Non-Members

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

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

See also Debugging Techniques.

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.