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
	Swaps the match result other with this 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 (const QString &name) const
bool	hasCaptured (QStringView 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 (const QString &name) const
	Returns the substring captured by the capturing group named name.
QString	captured (QStringView name) const
QStringView	capturedView (QStringView 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 (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.
qsizetype	capturedLength (const QString &name) const
	Returns the length of the substring captured by the capturing group named name.
qsizetype	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.
qsizetype	capturedStart (QStringView name) const
qsizetype	capturedLength (QStringView name) const
qsizetype	capturedEnd (QStringView name) const

Friends
class	QRegularExpression
struct	QRegularExpressionMatchPrivate
class	QRegularExpressionMatchIterator

Related Symbols
(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 192 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 2085 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::isValid.

~QRegularExpressionMatch()

QRegularExpressionMatch::~QRegularExpressionMatch

(

)

Destroys the match result.

Definition at line 2098 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 2109 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/3]

QString QRegularExpressionMatch::captured ( const QString &  name ) const

inline

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(), QString::isNull()

Definition at line 223 of file qregularexpression.h.

captured() [2/3]

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 2288 of file qregularexpression.cpp.

References capturedView(), and QStringView::toString().

Referenced by capturedTexts(), QQmlJS::Dom::DomEnvironment::loadModuleDependency(), Parser::parseMetadata(), and QGLXContext::queryDummyContext().

Here is the call graph for this function:

Here is the caller graph for this function:

captured() [3/3]

QString QRegularExpressionMatch::captured

(

QStringView

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.

See also

capturedView(), capturedStart(), capturedEnd(), capturedLength(), QString::isNull()

Definition at line 2342 of file qregularexpression.cpp.

References capturedView(), qWarning, and QStringView::toString().

Here is the call graph for this function:

capturedEnd() [1/3]

qsizetype QRegularExpressionMatch::capturedEnd ( const QString &  name ) const

inline

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

Definition at line 238 of file qregularexpression.h.

capturedEnd() [2/3]

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 2428 of file qregularexpression.cpp.

References QList< T >::at(), QRegularExpressionMatchPrivate::capturedOffsets, and hasCaptured().

Referenced by capturedEnd(), and capturedLength().

Here is the call graph for this function:

Here is the caller graph for this function:

capturedEnd() [3/3]

qsizetype QRegularExpressionMatch::capturedEnd

(

QStringView

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.

See also

capturedStart(), capturedLength(), captured()

Definition at line 2522 of file qregularexpression.cpp.

References capturedEnd(), QRegularExpressionPrivate::captureIndexForName(), qWarning, and QRegularExpressionMatchPrivate::regularExpression.

Here is the call graph for this function:

capturedLength() [1/3]

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

inline

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

Definition at line 236 of file qregularexpression.h.

capturedLength() [2/3]

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 2415 of file qregularexpression.cpp.

References capturedEnd(), and capturedStart().

Referenced by capturedLength(), capturedView(), and src_gui_text_qsyntaxhighlighter::MyHighlighter::wrapper().

Here is the call graph for this function:

Here is the caller graph for this function:

capturedLength() [3/3]

qsizetype QRegularExpressionMatch::capturedLength

(

QStringView

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.

See also

capturedStart(), capturedEnd(), captured()

Definition at line 2500 of file qregularexpression.cpp.

References capturedLength(), QRegularExpressionPrivate::captureIndexForName(), qWarning, and QRegularExpressionMatchPrivate::regularExpression.

Here is the call graph for this function:

capturedStart() [1/3]

qsizetype QRegularExpressionMatch::capturedStart ( const QString &  name ) const

inline

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

Definition at line 234 of file qregularexpression.h.

capturedStart() [2/3]

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 2399 of file qregularexpression.cpp.

References QList< T >::at(), QRegularExpressionMatchPrivate::capturedOffsets, and hasCaptured().

Referenced by capturedLength(), capturedStart(), and capturedView().

Here is the call graph for this function:

Here is the caller graph for this function:

capturedStart() [3/3]

qsizetype QRegularExpressionMatch::capturedStart

(

QStringView

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.

See also

capturedEnd(), capturedLength(), captured()

Definition at line 2477 of file qregularexpression.cpp.

References capturedStart(), QRegularExpressionPrivate::captureIndexForName(), qWarning, and QRegularExpressionMatchPrivate::regularExpression.

Here is the call graph for this function:

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 2382 of file qregularexpression.cpp.

References captured(), QRegularExpressionMatchPrivate::capturedCount, and i.

Here is the call graph for this function:

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 2307 of file qregularexpression.cpp.

References capturedLength(), capturedStart(), hasCaptured(), QStringView::mid(), and QRegularExpressionMatchPrivate::subject.

Referenced by captured(), captured(), capturedView(), and QMessagePattern::setPattern().

Here is the call graph for this function:

Here is the caller graph for this function:

capturedView() [2/2]

QStringView QRegularExpressionMatch::capturedView

(

QStringView

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.

See also

captured(), capturedStart(), capturedEnd(), capturedLength(), QStringView::isNull()

Definition at line 2364 of file qregularexpression.cpp.

References capturedView(), QRegularExpressionPrivate::captureIndexForName(), qWarning, and QRegularExpressionMatchPrivate::regularExpression.

Here is the call graph for this function:

hasCaptured() [1/3]

bool QRegularExpressionMatch::hasCaptured ( const QString &  name ) const

inline

Definition at line 215 of file qregularexpression.h.

Referenced by capturedEnd(), capturedStart(), capturedView(), and hasCaptured().

Here is the caller graph for this function:

hasCaptured() [2/3]

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 2268 of file qregularexpression.cpp.

References QList< T >::at(), QRegularExpressionMatchPrivate::capturedOffsets, and lastCapturedIndex().

Here is the call graph for this function:

hasCaptured() [3/3]

bool QRegularExpressionMatch::hasCaptured

(

QStringView

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.

See also

captured(), hasMatch()

Definition at line 2240 of file qregularexpression.cpp.

References QRegularExpressionPrivate::captureIndexForName(), hasCaptured(), and QRegularExpressionMatchPrivate::regularExpression.

Here is the call graph for this function:

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 2540 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::hasMatch.

Referenced by checkTap(), checkTxt(), for(), LocalFileApi::Type::Accept::MimeType::Extension::fromQt(), and QRegularExpressionMatchIteratorPrivate::hasNext().

Here is the caller graph for this function:

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 2555 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::hasPartialMatch.

Referenced by QRegularExpressionMatchIteratorPrivate::hasNext().

Here is the caller graph for this function:

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 2567 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::isValid.

Referenced by QRegularExpressionMatchIteratorPrivate::hasNext(), and QRegularExpressionMatchIterator::isValid().

Here is the caller graph for this function:

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 2214 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::capturedCount.

Referenced by hasCaptured().

Here is the caller graph for this function:

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 2195 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::matchOptions.

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 2183 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::matchType.

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 2132 of file qregularexpression.cpp.

References match().

Here is the call graph for this function:

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 200 of file qregularexpression.h.

References d, and match().

Here is the call graph for this function:

regularExpression()

QRegularExpression QRegularExpressionMatch::regularExpression

(

)

const

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

See also

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

Definition at line 2170 of file qregularexpression.cpp.

References QRegularExpressionMatchPrivate::regularExpression.

swap()

void QRegularExpressionMatch::swap ( QRegularExpressionMatch &  other )

inlinenoexcept

Swaps the match result other with this match result.

This operation is very fast and never fails.

Definition at line 202 of file qregularexpression.h.

References d, and other().

Here is the call graph for this function:

Friends And Related Symbol Documentation

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 2859 of file qregularexpression.cpp.

References debug, i, and match().

Here is the call graph for this function:

QRegularExpression

friend class QRegularExpression

friend

Definition at line 246 of file qregularexpression.h.

QRegularExpressionMatchIterator

friend class QRegularExpressionMatchIterator

friend

Definition at line 248 of file qregularexpression.h.

QRegularExpressionMatchPrivate

friend struct QRegularExpressionMatchPrivate

friend

Definition at line 247 of file qregularexpression.h.

---

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

• qtbase/src/corelib/text/qregularexpression.h
• qtbase/src/corelib/text/qregularexpression.cpp