class QRegularExpressionMatchIterator

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

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

A QRegularExpressionMatchIterator object is a forward only Java-like iterator; it can be obtained by calling the 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
re = QRegularExpression("(\\w+)")
subject = QString("the quick fox")
i = re.globalMatch(subject)
while i.hasNext():
    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 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"
re = QRegularExpression(R"(\w+)")
subject = QString("the quick fox")
for match in 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.

__init__()

Constructs an empty, valid QRegularExpressionMatchIterator object. The regular expression is set to a default-constructed one; the match type to NoMatch and the match options to 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.

__init__(iterator)
Parameters:

iterator – QRegularExpressionMatchIterator

Constructs a QRegularExpressionMatchIterator object as a copy of iterator.

See also

operator=()

hasNext()
Return type:

bool

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

See also

next()

isValid()
Return type:

bool

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

matchOptions()
Return type:

Combination of MatchOption

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

matchType()
Return type:

MatchType

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

next()
Return type:

QRegularExpressionMatch

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.

peekNext()
Return type:

QRegularExpressionMatch

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.

regularExpression()
Return type:

QRegularExpression

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

swap(other)
Parameters:

other – QRegularExpressionMatchIterator

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