Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
Public Member Functions | Friends | List of all members
QRegularExpressionMatchIterator Class Reference

\inmodule QtCore \reentrant More...

#include <qregularexpression.h>

+ Collaboration diagram for QRegularExpressionMatchIterator:

Public Member Functions

 QRegularExpressionMatchIterator ()
 
 ~QRegularExpressionMatchIterator ()
 Destroys the QRegularExpressionMatchIterator object.
 
 QRegularExpressionMatchIterator (const QRegularExpressionMatchIterator &iterator)
 Constructs a QRegularExpressionMatchIterator object as a copy of iterator.
 
 QRegularExpressionMatchIterator (QRegularExpressionMatchIterator &&iterator)=default
 
QRegularExpressionMatchIterator & operator= (const QRegularExpressionMatchIterator &iterator)
 Assigns the iterator iterator to this object, and returns a reference to the copy.
 
QRegularExpressionMatchIterator & operator= (QRegularExpressionMatchIterator &&iterator) noexcept
 Move-assigns the iterator to this object, and returns a reference to the result.
 
void swap (QRegularExpressionMatchIterator &other) noexcept
 Swaps the iterator other with this iterator object.
 
bool 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.
 
bool hasNext () const
 Returns true if there is at least one match result ahead of the iterator; otherwise it returns false.
 
QRegularExpressionMatch next ()
 Returns the next match result and advances the iterator by one position.
 
QRegularExpressionMatch peekNext () const
 Returns the next match result without moving the iterator.
 
QRegularExpression regularExpression () const
 Returns the QRegularExpression object whose globalMatch() function returned this object.
 
QRegularExpression::MatchType 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().
 
QRegularExpression::MatchOptions 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().
 

Friends

class QRegularExpression
 
Q_CORE_EXPORT QtPrivate::QRegularExpressionMatchIteratorRangeBasedForIterator begin (const QRegularExpressionMatchIterator &iterator)
 
QtPrivate::QRegularExpressionMatchIteratorRangeBasedForIteratorSentinel end (const QRegularExpressionMatchIterator &)
 

Detailed Description

\inmodule QtCore \reentrant

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

Since
5.0

\keyword regular expression iterator

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, QRegularExpressionMatch

Definition at line 286 of file qregularexpression.h.

Constructor & Destructor Documentation

◆ QRegularExpressionMatchIterator() [1/3]

QRegularExpressionMatchIterator::QRegularExpressionMatchIterator ( )
Since
5.1

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.

Definition at line 2570 of file qregularexpression.cpp.

◆ ~QRegularExpressionMatchIterator()

QRegularExpressionMatchIterator::~QRegularExpressionMatchIterator ( )

Destroys the QRegularExpressionMatchIterator object.

Definition at line 2581 of file qregularexpression.cpp.

◆ QRegularExpressionMatchIterator() [2/3]

QRegularExpressionMatchIterator::QRegularExpressionMatchIterator ( const QRegularExpressionMatchIterator & iterator)

Constructs a QRegularExpressionMatchIterator object as a copy of iterator.

See also
operator=()

Definition at line 2593 of file qregularexpression.cpp.

◆ QRegularExpressionMatchIterator() [3/3]

QRegularExpressionMatchIterator::QRegularExpressionMatchIterator ( QRegularExpressionMatchIterator && iterator)
default
Since
6.1

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.

See also
operator=()

Member Function Documentation

◆ hasNext()

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

Definition at line 2659 of file qregularexpression.cpp.

References QRegularExpressionMatchIteratorPrivate::hasNext().

Referenced by next(), and peekNext().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ isValid()

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

Definition at line 2648 of file qregularexpression.cpp.

References QRegularExpressionMatch::isValid(), and QRegularExpressionMatchIteratorPrivate::next.

+ Here is the call graph for this function:

◆ matchOptions()

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

Definition at line 2725 of file qregularexpression.cpp.

References QRegularExpressionMatchIteratorPrivate::matchOptions.

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

Definition at line 2713 of file qregularexpression.cpp.

References QRegularExpressionMatchIteratorPrivate::matchType.

◆ next()

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.

Definition at line 2684 of file qregularexpression.cpp.

References QExplicitlySharedDataPointer< T >::constData(), QExplicitlySharedDataPointer< T >::detach(), hasNext(), QRegularExpressionMatchIteratorPrivate::next, QRegularExpressionMatchPrivate::nextMatch(), and qWarning.

Referenced by QtAndroidFileDialogHelper::nameFilterExtensions().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ operator=() [1/2]

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

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

Definition at line 2616 of file qregularexpression.cpp.

◆ operator=() [2/2]

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

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.

Definition at line 294 of file qregularexpression.h.

References d, and swap().

+ Here is the call graph for this function:

◆ peekNext()

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.

Definition at line 2670 of file qregularexpression.cpp.

References hasNext(), QRegularExpressionMatchIteratorPrivate::next, and qWarning.

+ Here is the call graph for this function:

◆ regularExpression()

QRegularExpression QRegularExpressionMatchIterator::regularExpression ( ) const

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

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

Definition at line 2701 of file qregularexpression.cpp.

References QRegularExpressionMatchIteratorPrivate::regularExpression.

◆ swap()

void QRegularExpressionMatchIterator::swap ( QRegularExpressionMatchIterator & other)
inlinenoexcept

Swaps the iterator other with this iterator object.

This operation is very fast and never fails.

Definition at line 296 of file qregularexpression.h.

References d, and other().

Referenced by operator=().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ begin

Q_CORE_EXPORT QtPrivate::QRegularExpressionMatchIteratorRangeBasedForIterator begin ( const QRegularExpressionMatchIterator & iterator)
friend

Definition at line 2733 of file qregularexpression.cpp.

◆ end

QtPrivate::QRegularExpressionMatchIteratorRangeBasedForIteratorSentinel end ( const QRegularExpressionMatchIterator & )
friend

Definition at line 311 of file qregularexpression.h.

◆ QRegularExpression

friend class QRegularExpression
friend

Definition at line 309 of file qregularexpression.h.

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