Back to Doc.qt.io
Contact Us Blog Download Qt

QRegularExpressionMatchIterator Class

The QRegularExpressionMatchIterator class provides an iterator on the results of a global match of a QRegularExpression object against a string. More...

Header: #include <QRegularExpressionMatchIterator>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Note: All functions in this class are reentrant.

Public Functions

QRegularExpressionMatchIterator()
QRegularExpressionMatchIterator(const QRegularExpressionMatchIterator &iterator)
(since 6.1) QRegularExpressionMatchIterator(QRegularExpressionMatchIterator &&iterator)
~QRegularExpressionMatchIterator()
bool hasNext() const
bool isValid() const
QRegularExpression::MatchOptions matchOptions() const
QRegularExpression::MatchType matchType() const
QRegularExpressionMatch next()
QRegularExpressionMatch peekNext() const
QRegularExpression regularExpression() const
void swap(QRegularExpressionMatchIterator &other)
QRegularExpressionMatchIterator &operator=(QRegularExpressionMatchIterator &&iterator)
QRegularExpressionMatchIterator &operator=(const QRegularExpressionMatchIterator &iterator)

Detailed Description

A QRegularExpressionMatchIterator object is a forward only Java-like iterator; it can be obtained by calling the QRegularExpression::globalMatch() function. A new QRegularExpressionMatchIterator will be positioned before the first result. You can then call the hasNext() function to check if there are more results available; if so, the next() function will return the next result and advance the iterator.

Each result is a QRegularExpressionMatch object holding all the information for that result (including captured substrings).

For instance:

// extracts the words
QRegularExpression re("(\\w+)");
QString subject("the quick fox");
QRegularExpressionMatchIterator i = re.globalMatch(subject);
while (i.hasNext()) {
    QRegularExpressionMatch match = i.next();
    // ...
}

Moreover, QRegularExpressionMatchIterator offers a peekNext() function to get the next result without advancing the iterator.

Starting with Qt 6.0, it is also possible to simply use the result of QRegularExpression::globalMatch in a range-based for loop, for instance like this:

// using a raw string literal, R"(raw_characters)", to be able to use "\w"
// without having to escape the backslash as "\\w"
QRegularExpression re(R"(\w+)");
QString subject("the quick fox");
for (const QRegularExpressionMatch &match : re.globalMatch(subject)) {
    // ...
}

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 and QRegularExpressionMatch.

Member Function Documentation

QRegularExpressionMatchIterator::QRegularExpressionMatchIterator()

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

Invoking the hasNext() member function on the constructed object will return false, as the iterator is not iterating on a valid sequence of matches.

QRegularExpressionMatchIterator::QRegularExpressionMatchIterator(const QRegularExpressionMatchIterator &iterator)

Constructs a QRegularExpressionMatchIterator object as a copy of iterator.

See also operator=().

[noexcept, since 6.1] QRegularExpressionMatchIterator::QRegularExpressionMatchIterator(QRegularExpressionMatchIterator &&iterator)

Constructs a QRegularExpressionMatchIterator object by moving from iterator.

Note that a moved-from QRegularExpressionMatchIterator 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] QRegularExpressionMatchIterator::~QRegularExpressionMatchIterator()

Destroys the QRegularExpressionMatchIterator object.

bool QRegularExpressionMatchIterator::hasNext() const

Returns true if there is at least one match result ahead of the iterator; otherwise it returns false.

See also next().

bool QRegularExpressionMatchIterator::isValid() const

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

See also QRegularExpression::globalMatch() and QRegularExpression::isValid().

QRegularExpression::MatchOptions QRegularExpressionMatchIterator::matchOptions() const

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

See also QRegularExpression::globalMatch(), regularExpression(), and matchType().

QRegularExpression::MatchType QRegularExpressionMatchIterator::matchType() const

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

See also QRegularExpression::globalMatch(), regularExpression(), and matchOptions().

QRegularExpressionMatch QRegularExpressionMatchIterator::next()

Returns the next match result and advances the iterator by one position.

Note: Calling this function when the iterator is at the end of the result set leads to undefined results.

QRegularExpressionMatch QRegularExpressionMatchIterator::peekNext() const

Returns the next match result without moving the iterator.

Note: Calling this function when the iterator is at the end of the result set leads to undefined results.

QRegularExpression QRegularExpressionMatchIterator::regularExpression() const

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

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

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

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

[noexcept] QRegularExpressionMatchIterator &QRegularExpressionMatchIterator::operator=(QRegularExpressionMatchIterator &&iterator)

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

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

QRegularExpressionMatchIterator &QRegularExpressionMatchIterator::operator=(const QRegularExpressionMatchIterator &iterator)

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

© 2024 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.