QtBase
v6.3.1
|
The QRegularExpression class provides pattern matching using regular expressions. More...
#include <qregularexpression.h>
Public Types | |
enum | PatternOption { NoPatternOption = 0x0000 , CaseInsensitiveOption = 0x0001 , DotMatchesEverythingOption = 0x0002 , MultilineOption = 0x0004 , ExtendedPatternSyntaxOption = 0x0008 , InvertedGreedinessOption = 0x0010 , DontCaptureOption = 0x0020 , UseUnicodePropertiesOption = 0x0040 } |
enum | MatchType { NormalMatch = 0 , PartialPreferCompleteMatch , PartialPreferFirstMatch , NoMatch } |
enum | MatchOption { NoMatchOption = 0x0000 , AnchorAtOffsetMatchOption = 0x0001 , Q_DECL_ENUMERATOR_DEPRECATED_X , DontCheckSubjectStringMatchOption = 0x0002 } |
enum | WildcardConversionOption { DefaultWildcardConversion = 0x0 , UnanchoredWildcardConversion = 0x1 } |
Static Public Member Functions | |
static QString | escape (const QString &str) |
static QString | wildcardToRegularExpression (const QString &str, WildcardConversionOptions options=DefaultWildcardConversion) |
static QString | anchoredPattern (const QString &expression) |
static QString | escape (QStringView str) |
static QString | wildcardToRegularExpression (QStringView str, WildcardConversionOptions options=DefaultWildcardConversion) |
static QString | anchoredPattern (QStringView expression) |
static QRegularExpression | fromWildcard (QStringView pattern, Qt::CaseSensitivity cs=Qt::CaseInsensitive, WildcardConversionOptions options=DefaultWildcardConversion) |
Friends | |
struct | QRegularExpressionPrivate |
class | QRegularExpressionMatch |
struct | QRegularExpressionMatchPrivate |
class | QRegularExpressionMatchIterator |
Q_CORE_EXPORT size_t | qHash (const QRegularExpression &key, size_t seed) noexcept |
Related Functions | |
(Note that these are not member functions.) | |
size_t | qHash (const QRegularExpression &key, size_t seed) noexcept |
QDataStream & | operator<< (QDataStream &out, const QRegularExpression &re) |
QDataStream & | operator>> (QDataStream &in, QRegularExpression &re) |
QDebug | operator<< (QDebug debug, const QRegularExpression &re) |
QDebug | operator<< (QDebug debug, QRegularExpression::PatternOptions patternOptions) |
The QRegularExpression class provides pattern matching using regular expressions.
\inmodule QtCore \reentrant
\keyword regular expression
Regular expressions, or {regexps}, are a very powerful tool to handle strings and texts. This is useful in many contexts, e.g.,
\table \row
This document is by no means a complete reference to pattern matching using regular expressions, and the following parts will require the reader to have some basic knowledge about Perl-like regular expressions and their pattern syntax.
Good references about regular expressions include:
\list
Definition at line 68 of file qregularexpression.h.
\value NoMatchOption No match options are set.
\value AnchoredMatchOption Use AnchorAtOffsetMatchOption instead.
\value AnchorAtOffsetMatchOption The match is constrained to start exactly at the offset passed to match() in order to be successful, even if the pattern string does not contain any metacharacter that anchors the match at that point. Note that passing this option does not anchor the end of the match to the end of the subject; if you want to fully anchor a regular expression, use anchoredPattern(). This enum value has been introduced in Qt 6.0.
\value DontCheckSubjectStringMatchOption The subject string is not checked for UTF-16 validity before attempting a match. Use this option with extreme caution, as attempting to match an invalid string may crash the program and/or constitute a security issue. This enum value has been introduced in Qt 5.4.
Enumerator | |
---|---|
NoMatchOption | |
AnchorAtOffsetMatchOption | |
Q_DECL_ENUMERATOR_DEPRECATED_X | |
DontCheckSubjectStringMatchOption |
Definition at line 117 of file qregularexpression.h.
The MatchType enum defines the type of the match that should be attempted against the subject string.
\value NormalMatch A normal match is done.
\value PartialPreferCompleteMatch The pattern string is matched partially against the subject string. If a partial match is found, then it is recorded, and other matching alternatives are tried as usual. If a complete match is then found, then it's preferred to the partial match; in this case only the complete match is reported. If instead no complete match is found (but only the partial one), then the partial one is reported.
\value PartialPreferFirstMatch The pattern string is matched partially against the subject string. If a partial match is found, then matching stops and the partial match is reported. In this case, other matching alternatives (potentially leading to a complete match) are not tried. Moreover, this match type assumes that the subject string only a substring of a larger text, and that (in this text) there are other characters beyond the end of the subject string. This can lead to surprising results; see the discussion in the \l{partial matching} section for more details.
\value NoMatch No matching is done. This value is returned as the match type by a default constructed QRegularExpressionMatch or QRegularExpressionMatchIterator. Using this match type is not very useful for the user, as no matching ever happens. This enum value has been introduced in Qt 5.1.
Enumerator | |
---|---|
NormalMatch | |
PartialPreferCompleteMatch | |
PartialPreferFirstMatch | |
NoMatch |
Definition at line 110 of file qregularexpression.h.
The PatternOption enum defines modifiers to the way the pattern string should be interpreted, and therefore the way the pattern matches against a subject string.
\value NoPatternOption No pattern options are set.
\value CaseInsensitiveOption The pattern should match against the subject string in a case insensitive way. This option corresponds to the /i modifier in Perl regular expressions.
\value DotMatchesEverythingOption The dot metacharacter ({.}) in the pattern string is allowed to match any character in the subject string, including newlines (normally, the dot does not match newlines). This option corresponds to the
{/s} modifier in Perl regular expressions.
\value MultilineOption The caret ({^}) and the dollar (
{$}) metacharacters in the pattern string are allowed to match, respectively, immediately after and immediately before any newline in the subject string, as well as at the very beginning and at the very end of the subject string. This option corresponds to the
{/m} modifier in Perl regular expressions.
\value ExtendedPatternSyntaxOption Any whitespace in the pattern string which is not escaped and outside a character class is ignored. Moreover, an unescaped sharp ({#}) outside a character class causes all the following characters, until the first newline (included), to be ignored. This can be used to increase the readability of a pattern string as well as put comments inside regular expressions; this is particularly useful if the pattern string is loaded from a file or written by the user, because in C++ code it is always possible to use the rules for string literals to put comments outside the pattern string. This option corresponds to the {/x} modifier in Perl regular expressions.
\value InvertedGreedinessOption The greediness of the quantifiers is inverted: {*},
{+},
{?},
{{m,n}}, etc. become lazy, while their lazy versions (
{*?},
{+?},
{??},
{{m,n}?}, etc.) become greedy. There is no equivalent for this option in Perl regular expressions.
\value DontCaptureOption The non-named capturing groups do not capture substrings; named capturing groups still work as intended, as well as the implicit capturing group number 0 corresponding to the entire match. There is no equivalent for this option in Perl regular expressions.
\value UseUnicodePropertiesOption The meaning of the {\w},
{\d}, etc., character classes, as well as the meaning of their counterparts (
{\W},
{\D}, etc.), is changed from matching ASCII characters only to matching any character with the corresponding Unicode property. For instance,
{\d} is changed to match any character with the Unicode Nd (decimal digit) property;
{\w} to match any character with either the Unicode L (letter) or N (digit) property, plus underscore, and so on. This option corresponds to the
{/u} modifier in Perl regular expressions.
Enumerator | |
---|---|
NoPatternOption | |
CaseInsensitiveOption | |
DotMatchesEverythingOption | |
MultilineOption | |
ExtendedPatternSyntaxOption | |
InvertedGreedinessOption | |
DontCaptureOption | |
UseUnicodePropertiesOption |
Definition at line 71 of file qregularexpression.h.
The WildcardConversionOption enum defines modifiers to the way a wildcard glob pattern gets converted to a regular expression pattern.
\value DefaultWildcardConversion No conversion options are set.
\value UnanchoredWildcardConversion The conversion will not anchor the pattern. This allows for partial string matches of wildcard expressions.
Enumerator | |
---|---|
DefaultWildcardConversion | |
UnanchoredWildcardConversion |
Definition at line 152 of file qregularexpression.h.
QRegularExpression::QRegularExpression | ( | ) |
Constructs a QRegularExpression object with an empty pattern and no pattern options.
Definition at line 1369 of file qregularexpression.cpp.
|
explicit |
Constructs a QRegularExpression object using the given pattern as pattern and the options as the pattern options.
Definition at line 1380 of file qregularexpression.cpp.
QRegularExpression::QRegularExpression | ( | const QRegularExpression & | re | ) |
Constructs a QRegularExpression object as a copy of re.
Definition at line 1392 of file qregularexpression.cpp.
|
default |
Constructs a QRegularExpression object by moving from re.
Note that a moved-from QRegularExpression can only be destroyed or assigned to. The effect of calling other functions than the destructor or one of the assignment operators is undefined.
QRegularExpression::~QRegularExpression | ( | ) |
Destroys the QRegularExpression object.
Definition at line 1414 of file qregularexpression.cpp.
Definition at line 168 of file qregularexpression.h.
|
static |
Returns the expression wrapped between the {\A} and
{\z} anchors to be used for exact matching.
Definition at line 2045 of file qregularexpression.cpp.
int QRegularExpression::captureCount | ( | ) | const |
Returns the number of capturing groups inside the pattern string, or -1 if the regular expression is not valid.
Definition at line 1495 of file qregularexpression.cpp.
QString QRegularExpression::errorString | ( | ) | const |
Returns a textual description of the error found when checking the validity of the regular expression, or "no error" if no error was found.
Definition at line 1578 of file qregularexpression.cpp.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Definition at line 158 of file qregularexpression.h.
|
static |
Escapes all characters of str so that they no longer have any special meaning when used as a regular expression pattern string, and returns the escaped string. For instance:
This is very convenient in order to build patterns from arbitrary strings:
{[A-Z]},
{[a-z]} and
{[0-9]} ranges, as well as the underscore (
{_}) character. The only difference with Perl is that a literal NUL inside str is escaped with the sequence
{"\\0"} (backslash +
{'0'}), instead of
{"\\\0"} (backslash +
{NUL}). Definition at line 1824 of file qregularexpression.cpp.
|
static |
Equivalent to
Definition at line 2025 of file qregularexpression.cpp.
QRegularExpressionMatchIterator QRegularExpression::globalMatch | ( | const QString & | subject, |
qsizetype | offset = 0 , |
||
MatchType | matchType = NormalMatch , |
||
MatchOptions | matchOptions = NoMatchOption |
||
) | const |
Attempts to perform a global match of the regular expression against the given subject string, starting at the position offset inside the subject, using a match of type matchType and honoring the given matchOptions.
The returned QRegularExpressionMatchIterator is positioned before the first match result (if any).
Definition at line 1695 of file qregularexpression.cpp.
QRegularExpressionMatchIterator QRegularExpression::globalMatch | ( | QStringView | subjectView, |
qsizetype | offset = 0 , |
||
MatchType | matchType = NormalMatch , |
||
MatchOptions | matchOptions = NoMatchOption |
||
) | const |
Attempts to perform a global match of the regular expression against the given subjectView string view, starting at the position offset inside the subject, using a match of type matchType and honoring the given matchOptions.
The returned QRegularExpressionMatchIterator is positioned before the first match result (if any).
Definition at line 1727 of file qregularexpression.cpp.
bool QRegularExpression::isValid | ( | ) | const |
Returns true
if the regular expression is a valid regular expression (that is, it contains no syntax errors, etc.), or false otherwise. Use errorString() to obtain a textual description of the error.
Definition at line 1566 of file qregularexpression.cpp.
QRegularExpressionMatch QRegularExpression::match | ( | const QString & | subject, |
qsizetype | offset = 0 , |
||
MatchType | matchType = NormalMatch , |
||
MatchOptions | matchOptions = NoMatchOption |
||
) | const |
Attempts to match the regular expression against the given subject string, starting at the position offset inside the subject, using a match of type matchType and honoring the given matchOptions.
The returned QRegularExpressionMatch object contains the results of the match.
Definition at line 1633 of file qregularexpression.cpp.
QRegularExpressionMatch QRegularExpression::match | ( | QStringView | subjectView, |
qsizetype | offset = 0 , |
||
MatchType | matchType = NormalMatch , |
||
MatchOptions | matchOptions = NoMatchOption |
||
) | const |
Attempts to match the regular expression against the given subjectView string view, starting at the position offset inside the subject, using a match of type matchType and honoring the given matchOptions.
The returned QRegularExpressionMatch object contains the results of the match.
Definition at line 1664 of file qregularexpression.cpp.
QStringList QRegularExpression::namedCaptureGroups | ( | ) | const |
Returns a list of captureCount() + 1 elements, containing the names of the named capturing groups in the pattern string. The list is sorted such that the element of the list at position {i} is the name of the
{i}-th capturing group, if it has a name, or an empty string if that capturing group is unnamed.
For instance, given the regular expression
namedCaptureGroups() will return the following list:
which corresponds to the fact that the capturing group #0 (corresponding to the whole match) has no name, the capturing group #1 has name "day", the capturing group #2 has name "month", etc.
If the regular expression is not valid, returns an empty list.
Definition at line 1527 of file qregularexpression.cpp.
|
inline |
Returns true
if the regular expression is different from re, or false otherwise.
Definition at line 181 of file qregularexpression.h.
QRegularExpression & QRegularExpression::operator= | ( | const QRegularExpression & | re | ) |
Assigns the regular expression re to this object, and returns a reference to the copy. Both the pattern and the pattern options are copied.
Move-assigns the regular expression re to this object, and returns a reference to the result. Both the pattern and the pattern options are copied.
Note that a moved-from QRegularExpression 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 1424 of file qregularexpression.cpp.
bool QRegularExpression::operator== | ( | const QRegularExpression & | re | ) | const |
Returns true
if the regular expression is equal to re, or false otherwise. Two QRegularExpression objects are equal if they have the same pattern string and the same pattern options.
Definition at line 1761 of file qregularexpression.cpp.
void QRegularExpression::optimize | ( | ) | const |
Compiles the pattern immediately, including JIT compiling it (if the JIT is enabled) for optimization.
Definition at line 1749 of file qregularexpression.cpp.
QString QRegularExpression::pattern | ( | ) | const |
Returns the pattern string of the regular expression.
Definition at line 1442 of file qregularexpression.cpp.
qsizetype QRegularExpression::patternErrorOffset | ( | ) | const |
Returns the offset, inside the pattern string, at which an error was found when checking the validity of the regular expression. If no error was found, then -1 is returned.
Definition at line 1612 of file qregularexpression.cpp.
QRegularExpression::PatternOptions QRegularExpression::patternOptions | ( | ) | const |
Returns the pattern options for the regular expression.
Definition at line 1467 of file qregularexpression.cpp.
Sets the pattern string of the regular expression to pattern. The pattern options are left unchanged.
Definition at line 1453 of file qregularexpression.cpp.
void QRegularExpression::setPatternOptions | ( | PatternOptions | options | ) |
Sets the given options as the pattern options of the regular expression. The pattern string is left unchanged.
Definition at line 1478 of file qregularexpression.cpp.
|
inlinenoexcept |
Swaps the regular expression other with this regular expression. This operation is very fast and never fails.
Definition at line 97 of file qregularexpression.h.
|
inlinestatic |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
Definition at line 163 of file qregularexpression.h.
|
static |
Returns a regular expression representation of the given glob pattern. The transformation is targeting file path globbing, which means in particular that path separators receive special treatment. This implies that it is not just a basic translation from "*" to ".*".
By default, the returned regular expression is fully anchored. In other words, there is no need of calling anchoredPattern() again on the result. To get an a regular expression that is not anchored, pass UnanchoredWildcardConversion as the conversion options.
This implementation follows closely the definition of wildcard for glob patterns: \table \row
{[?]}).More information about the implementation can be found in: \list
{man
7 glob} \endlistDefinition at line 1931 of file qregularexpression.cpp.
|
related |
Writes the regular expression re to stream out.
Definition at line 2752 of file qregularexpression.cpp.
|
related |
Writes the regular expression re into the debug object debug for debugging purposes.
Definition at line 2785 of file qregularexpression.cpp.
Writes the pattern options patternOptions into the debug object debug for debugging purposes.
Definition at line 2800 of file qregularexpression.cpp.
|
related |
Reads a regular expression from stream in into re.
Definition at line 2765 of file qregularexpression.cpp.
|
related |
Returns the hash value for key, using seed to seed the calculation.
Definition at line 1794 of file qregularexpression.cpp.
|
friend |
Returns the hash value for key, using seed to seed the calculation.
Definition at line 1794 of file qregularexpression.cpp.
|
friend |
Definition at line 185 of file qregularexpression.h.
|
friend |
Definition at line 187 of file qregularexpression.h.
|
friend |
Definition at line 186 of file qregularexpression.h.
|
friend |
Definition at line 184 of file qregularexpression.h.