QRegularExpression Class

The QRegularExpression class provides pattern matching using regular expressions. More…

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

A QRegularExpression holds a Perl-compatible pattern. match() looks for the first match in a string and returns a QRegularExpressionMatch with the captured groups; globalMatch() iterates over all matches:

QRegularExpression re(u"(\\d+)-(?<month>\\d+)"_s);
QRegularExpressionMatch m = re.match(u"due 2024-06"_s);
if (m.hasMatch()) {
    QString year = m.captured(1);       // "2024"
    QString month = m.captured("month"); // "06"
}

for (const QRegularExpressionMatch &word : QRegularExpression(u"\\w+"_s).globalMatch(text))
    words << word.captured();

The pattern syntax follows PCRE2: literals and escapes, character classes (including POSIX classes and \p{...} properties), the anchors ^, $, \A, \z, \Z, \b, \B and \G, greedy, lazy and possessive quantifiers, capturing, named, non-capturing and atomic groups, lookahead and lookbehind, back references, inline option settings such as (?i), \Q...\E quoting, \K and comments.

See also QRegularExpressionMatch, QRegularExpressionMatchIterator and QString::indexOf().

Differences from Qt

Member Type Documentation

enum QRegularExpression::MatchOption

typedef QRegularExpression::MatchOptions

The MatchOptions type is a typedef for QFlags<MatchOption>. It stores an OR combination of MatchOption values.

enum QRegularExpression::MatchType

enum QRegularExpression::PatternOption

typedef QRegularExpression::PatternOptions

The PatternOptions type is a typedef for QFlags<PatternOption>. It stores an OR combination of PatternOption values.

enum QRegularExpression::WildcardConversionOption

This function was introduced in 6.0.

typedef QRegularExpression::WildcardConversionOptions

The WildcardConversionOptions type is a typedef for QFlags<WildcardConversionOption>. It stores an OR combination of WildcardConversionOption values.

Member Function Documentation

QRegularExpression::QRegularExpression()

Constructs a regular expression with an empty pattern, which is valid and matches the empty string at any position.

See also setPattern().

[explicit] QRegularExpression::QRegularExpression(const QString &pattern, PatternOptions options = NoPatternOption)

Constructs a regular expression for pattern with the pattern options options. The pattern is compiled when it is first used; check isValid() to find out whether it is well formed.

QRegularExpression::QRegularExpression(const QRegularExpression &re)

Constructs a copy of re.

QRegularExpression::QRegularExpression(QRegularExpression &&re)

Move-constructs a regular expression from re, which becomes a valid empty expression.

QRegularExpression::~QRegularExpression()

Destroys the regular expression.

[static] QString QRegularExpression::anchoredPattern(QStringView expression)

Returns expression wrapped in \A(?: and )\z, so that it only matches a whole string.

This function was introduced in 5.12.

int QRegularExpression::captureCount() const

Returns the number of capturing groups in the pattern, or -1 if the pattern is invalid. Group 0, the whole match, is not counted.

See also namedCaptureGroups().

QString QRegularExpression::errorString() const

Returns a description of the error found in the pattern, or "no error" if the pattern is valid.

See also isValid() and patternErrorOffset().

[static] QString QRegularExpression::escape(QStringView str)

Returns str with every character that has a special meaning in a pattern escaped by a backslash, so that the result matches str literally. All characters other than ASCII letters, digits and _ are escaped; a null character becomes \0.

See also wildcardToRegularExpression().

[static] QRegularExpression QRegularExpression::fromWildcard(QStringView pattern, Qt::CaseSensitivity cs = Qt::CaseInsensitive, WildcardConversionOptions options = DefaultWildcardConversion)

Returns a regular expression for the shell wildcard pattern, converted with wildcardToRegularExpression() and the options options, matching with the case sensitivity cs.

This function was introduced in 6.0.

QRegularExpressionMatchIterator QRegularExpression::globalMatch(const QString &subject, qsizetype offset = 0, MatchType matchType = NormalMatch, MatchOptions matchOptions = NoMatchOption) const

Returns an iterator over the successive matches of the expression in subject, starting at offset, with the match type matchType and the options matchOptions.

See also match() and QRegularExpressionMatchIterator.

QRegularExpressionMatchIterator QRegularExpression::globalMatchView(QStringView subjectView, qsizetype offset = 0, MatchType matchType = NormalMatch, MatchOptions matchOptions = NoMatchOption) const

Returns an iterator over the matches in the text viewed by subjectView, starting at offset, with the match type matchType and the options matchOptions.

This function was introduced in 6.5.

See also globalMatch().

bool QRegularExpression::isValid() const

Returns true if the pattern is a well-formed regular expression; otherwise returns false.

See also errorString() and patternErrorOffset().

QRegularExpressionMatch QRegularExpression::match(const QString &subject, qsizetype offset = 0, MatchType matchType = NormalMatch, MatchOptions matchOptions = NoMatchOption) const

Matches the expression against subject, starting the search at offset, and returns the result. A negative offset counts from the end of the subject. matchType selects normal or partial matching and matchOptions how the match is anchored.

See also globalMatch() and QRegularExpressionMatch.

QRegularExpressionMatch QRegularExpression::matchView(QStringView subjectView, qsizetype offset = 0, MatchType matchType = NormalMatch, MatchOptions matchOptions = NoMatchOption) const

Matches the expression against the text viewed by subjectView, starting at offset, with the match type matchType and the options matchOptions.

This function was introduced in 6.5.

See also match().

QStringList QRegularExpression::namedCaptureGroups() const

Returns the names of the capturing groups, indexed by group number. The list has captureCount() + 1 entries; the first is empty (the whole match) and so are the entries of unnamed groups. An invalid pattern gives an empty list.

See also captureCount() and QRegularExpressionMatch::captured().

QRegularExpression & QRegularExpression::operator=(const QRegularExpression &re)

Assigns re to this object and returns a reference to it.

QRegularExpression & QRegularExpression::operator=(QRegularExpression &&re)

Move-assigns re to this object and returns a reference to it.

void QRegularExpression::optimize() const

Compiles the pattern now instead of at the first match. Nt has no JIT, so there is nothing else to optimize.

QString QRegularExpression::pattern() const

Returns the pattern string of the regular expression.

See also setPattern() and patternOptions().

qsizetype QRegularExpression::patternErrorOffset() const

Returns the offset in the pattern string at which an error was found, or -1 if the pattern is valid.

See also errorString() and isValid().

PatternOptions QRegularExpression::patternOptions() const

Returns the pattern options of the regular expression.

See also setPatternOptions() and pattern().

void QRegularExpression::setPattern(const QString &pattern)

Sets the pattern of the regular expression to pattern. The pattern options are kept.

See also pattern() and setPatternOptions().

void QRegularExpression::setPatternOptions(PatternOptions options)

Sets the pattern options to options.

See also patternOptions() and setPattern().

void QRegularExpression::swap(QRegularExpression &other)

Swaps this regular expression with other.

[static] QString QRegularExpression::wildcardToRegularExpression(QStringView pattern, WildcardConversionOptions options = DefaultWildcardConversion)

Returns a regular expression pattern equivalent to the shell wildcard pattern: * matches any sequence of characters, ? any single character and [...] a set of characters ([!...] negated). Unless options contains NonPathWildcardConversion, the wildcards do not match the path separator /; unless it contains UnanchoredWildcardConversion, the result is anchored to match the whole string.

This function was introduced in 5.12.

See also fromWildcard() and escape().