本页内容

QRegularExpression Class

QRegularExpression 类提供基于正则表达式的模式匹配功能。更多内容...

头文件: #include <QRegularExpression>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

注意:该类中的所有函数均为可重入函数。

QRegularExpression 比较

类别可比较类型
相等性QRegularExpression

公共类型

enum MatchOption { NoMatchOption, AnchoredMatchOption, AnchorAtOffsetMatchOption, DontCheckSubjectStringMatchOption }
flags MatchOptions
enum MatchType { NormalMatch, PartialPreferCompleteMatch, PartialPreferFirstMatch, NoMatch }
enum PatternOption { NoPatternOption, CaseInsensitiveOption, DotMatchesEverythingOption, MultilineOption, ExtendedPatternSyntaxOption, …, UseUnicodePropertiesOption }
flags PatternOptions
(since 6.0) enum WildcardConversionOption { DefaultWildcardConversion, UnanchoredWildcardConversion, NonPathWildcardConversion }
flags WildcardConversionOptions

公共函数

QRegularExpression()
QRegularExpression(const QString &pattern, QRegularExpression::PatternOptions options = NoPatternOption)
QRegularExpression(const QRegularExpression &re)
(since 6.1) QRegularExpression(QRegularExpression &&re)
~QRegularExpression()
int captureCount() const
QString errorString() const
QRegularExpressionMatchIterator globalMatch(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
(since 6.5) QRegularExpressionMatchIterator globalMatchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
bool isValid() const
QRegularExpressionMatch match(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
(since 6.5) QRegularExpressionMatch matchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
QStringList namedCaptureGroups() const
void optimize() const
QString pattern() const
qsizetype patternErrorOffset() const
QRegularExpression::PatternOptions patternOptions() const
void setPattern(const QString &pattern)
void setPatternOptions(QRegularExpression::PatternOptions options)
void swap(QRegularExpression &other)
QRegularExpression &operator=(QRegularExpression &&re)
QRegularExpression &operator=(const QRegularExpression &re)

静态公共成员

QString anchoredPattern(QStringView expression)
QString anchoredPattern(const QString &expression)
QString escape(QStringView str)
QString escape(const QString &str)
(since 6.0) QRegularExpression fromWildcard(QStringView pattern, Qt::CaseSensitivity cs = Qt::CaseInsensitive, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
QString wildcardToRegularExpression(QStringView pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
QString wildcardToRegularExpression(const QString &pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
size_t qHash(const QRegularExpression &key, size_t seed = 0)
bool operator!=(const QRegularExpression &lhs, const QRegularExpression &rhs)
QDataStream &operator<<(QDataStream &out, const QRegularExpression &re)
QDebug operator<<(QDebug debug, QRegularExpression::PatternOptions patternOptions)
QDebug operator<<(QDebug debug, const QRegularExpression &re)
bool operator==(const QRegularExpression &lhs, const QRegularExpression &rhs)
QDataStream &operator>>(QDataStream &in, QRegularExpression &re)

详细说明

正则表达式(regexps)是处理字符串和文本的非常强大的工具。它在许多场景中都很实用,例如:

验证正则表达式可以检测子字符串是否符合某些条件,例如是否为整数或是否不含空格。
搜索正则表达式提供的模式匹配功能比简单的子字符串匹配更强大,例如,匹配“mail”、“letter”或“correspondence”中的任意一个词,但不匹配“email”、“mailman”、“mailer”、“letterbox”等词。
查找和替换正则表达式可以将所有出现的子字符串替换为另一个子字符串,例如,将所有出现的&替换为&amp;,但&后面已经紧跟amp; 的情况除外。
字符串拆分正则表达式可用于确定字符串应在何处进行分割,例如分割以制表符分隔的字符串。

本文绝非关于正则表达式模式匹配的完整参考资料,后续部分将要求读者具备一些关于 Perl 式正则表达式及其模式语法的基础知识。

关于正则表达式的优质参考资料包括:

引言

QRegularExpression 实现了 Perl 兼容正则表达式。它完全支持 Unicode。有关 QRegularExpression 支持的正则表达式语法概述,请参阅前述的 pcrepattern(3) 手册页。 正则表达式由两部分组成:模式字符串和一组用于改变模式字符串含义的模式选项。

您可以通过向 QRegularExpression 构造函数传递一个字符串来设置模式字符串:

QRegularExpression re("a pattern");

这将模式字符串设置为a pattern 。您还可以使用setPattern()函数为现有的QRegularExpression对象设置模式:

QRegularExpression re;
re.setPattern("another pattern");

请注意,由于 C++ 字符串字面量规则,您必须将模式字符串中的所有反斜杠用另一个反斜杠转义:

// matches two digits followed by a space and a word
QRegularExpression re("\\d\\d \\w+");

// matches a backslash
QRegularExpression re2("\\\\");

或者,你可以使用原始字符串字面量,在这种情况下,你无需对模式中的反斜杠进行转义,R"(...)" 之间的所有字符均被视为原始字符。如下例所示,这简化了模式的编写:

// matches two digits followed by a space and a word
QRegularExpression re(R"(\d\d \w+)");

pattern() 函数返回 QRegularExpression 对象当前设置的正则表达式:

QRegularExpression re("a third pattern");
QString pattern = re.pattern(); // pattern == "a third pattern"

模式选项

可以通过设置一个或多个模式选项来修改模式字符串的含义。例如,可以通过设置 `QRegularExpression::CaseInsensitiveOption` 使模式不区分大小写。

您可以通过将选项传递给 QRegularExpression 构造函数来设置这些选项,如下所示:

// matches "Qt rocks", but also "QT rocks", "QT ROCKS", "qT rOcKs", etc.
QRegularExpression re("Qt rocks", QRegularExpression::CaseInsensitiveOption);

此外,您还可以对现有的 QRegularExpressionObject 调用setPatternOptions() 函数:

QRegularExpression re("^\\d+$");
re.setPatternOptions(QRegularExpression::MultilineOption);
// re matches any line in the subject string that contains only digits (but at least one)

可以通过调用patternOptions()函数,获取当前设置在QRegularExpression对象上的模式选项:

QRegularExpression re = QRegularExpression("^two.*words$", QRegularExpression::MultilineOption
                                                        | QRegularExpression::DotMatchesEverythingOption);

QRegularExpression::PatternOptions options = re.patternOptions();
// options == QRegularExpression::MultilineOption | QRegularExpression::DotMatchesEverythingOption

有关每个模式选项的更多信息,请参阅QRegularExpression::PatternOption 枚举的文档。

匹配类型和匹配选项

match() 和globalMatch() 函数的最后两个参数用于设置匹配类型和匹配选项。 匹配类型是QRegularExpression::MatchType 枚举的值;使用NormalMatch 匹配类型(默认值)将选择“传统”匹配算法。还可以启用正则表达式对目标字符串的部分匹配:更多详细信息请参阅partial matching 部分。

匹配选项是一组一个或多个QRegularExpression::MatchOption 值。它们会改变正则表达式与目标字符串进行特定匹配的方式。更多详情请参阅QRegularExpression::MatchOption 枚举的文档。

常规匹配

要执行匹配,只需调用match()函数并传入待匹配的字符串即可。我们将该字符串称为目标字符串。match()函数的返回结果是一个QRegularExpressionMatch 对象,可用于检查匹配结果。例如:

// match two digits followed by a space and a word
QRegularExpression re("\\d\\d \\w+");
QRegularExpressionMatch match = re.match("abc123 def");
bool hasMatch = match.hasMatch(); // true

如果匹配成功,可以使用(隐式)捕获组编号 0 来获取与整个模式匹配的子字符串(另请参阅关于extracting captured substrings 的章节):

QRegularExpression re("\\d\\d \\w+");
QRegularExpressionMatch match = re.match("abc123 def");
if (match.hasMatch()) {
    QString matched = match.captured(0); // matched == "23 def"
    // ...
}

还可以通过将偏移量作为match() 函数的参数传递,从目标字符串内的任意偏移量位置开始匹配。在下面的示例中,"12 abc" 没有被匹配,因为匹配是从偏移量 1 开始的:

QRegularExpression re("\\d\\d \\w+");
QRegularExpressionMatch match = re.match("12 abc 45 def", 1);
if (match.hasMatch()) {
    QString matched = match.captured(0); // matched == "45 def"
    // ...
}

提取捕获的子字符串

QRegularExpressionMatch 对象还包含有关模式字符串中捕获组所捕获的子字符串的信息。captured() 函数将返回第 n 个捕获组所捕获的字符串:

QRegularExpression re("^(\\d\\d)/(\\d\\d)/(\\d\\d\\d\\d)$");
QRegularExpressionMatch match = re.match("08/12/1985");
if (match.hasMatch()) {
    QString day = match.captured(1); // day == "08"
    QString month = match.captured(2); // month == "12"
    QString year = match.captured(3); // year == "1985"
    // ...
}

模式中的捕获组编号从1开始,隐式捕获组0用于捕获与整个模式匹配的子字符串。

还可以通过使用capturedStart() 和capturedEnd() 函数,获取每个捕获子字符串在目标字符串中的起始和结束偏移量:

QRegularExpression re("abc(\\d+)def");
QRegularExpressionMatch match = re.match("XYZabc123defXYZ");
if (match.hasMatch()) {
    int startOffset = match.capturedStart(1); // startOffset == 6
    int endOffset = match.capturedEnd(1); // endOffset == 9
    // ...
}

所有这些函数都有一个重载版本,该版本将QString 作为参数,用于提取命名捕获子字符串。例如:

QRegularExpression re("^(?<date>\\d\\d)/(?<month>\\d\\d)/(?<year>\\d\\d\\d\\d)$");
QRegularExpressionMatch match = re.match("08/12/1985");
if (match.hasMatch()) {
    QString date = match.captured("date"); // date == "08"
    QString month = match.captured("month"); // month == "12"
    QString year = match.captured("year"); // year == 1985
}

全局匹配

全局匹配可用于在目标字符串中查找给定正则表达式的所有出现位置。假设我们要从给定字符串中提取所有单词,其中单词是指与模式\w+ 匹配的子字符串。

QRegularExpression::globalMatch 返回一个QRegularExpressionMatchIterator ,这是一个类似于 Java 的向前迭代器,可用于遍历结果。例如:

QRegularExpression re("(\\w+)");
QRegularExpressionMatchIterator i = re.globalMatch("the quick fox");

由于这是一个类似 Java 的迭代器,因此 `QRegularExpressionMatchIterator ` 将指向第一个结果的正前方。每个结果都以 `QRegularExpressionMatch ` 对象的形式返回。如果还有至少一个结果,`hasNext()` 函数将返回 `true`;而 `next()` 将返回下一个结果并使迭代器向前移动。承接上一个示例:

QStringList words;
while (i.hasNext()) {
    QRegularExpressionMatch match = i.next();
    QString word = match.captured(1);
    words << word;
}
// words contains "the", "quick", "fox"

您还可以使用peekNext() 来获取下一个结果,而无需移动迭代器。

此外,还可以直接在基于范围的 for 循环中使用QRegularExpression::globalMatch 的返回值,例如如下所示:

// 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)) {
    // ...
}

可以向globalMatch() 函数传递一个起始偏移量和一个或多个匹配选项,这与使用match() 进行常规匹配完全相同。

部分匹配

当达到被匹配字符串的末尾,但仍需更多字符才能成功完成匹配时,即为部分匹配。请注意,部分匹配通常比普通匹配效率低得多,因为无法应用匹配算法的许多优化。

必须通过在调用QRegularExpression::match 或QRegularExpression::globalMatch 时,将匹配类型指定为PartialPreferCompleteMatch 或PartialPreferFirstMatch ,来显式请求部分匹配。如果找到了部分匹配,那么对match()返回的QRegularExpressionMatch 对象调用hasMatch()函数将返回false ,但hasPartialMatch()将返回true 。

当找到部分匹配时,不会返回任何捕获的子字符串,且与整个匹配对应的(隐式)捕获组 0 会捕获源字符串中部分匹配的子字符串。

请注意,即使请求的是部分匹配,如果找到了完全匹配,仍可能返回完全匹配的结果;在此情况下,hasMatch() 将返回true ,而hasPartialMatch() 将返回false 。QRegularExpressionMatch 绝不会同时报告部分匹配和完全匹配。

部分匹配主要在两种场景下有用:实时验证用户输入以及增量/多段匹配。

验证用户输入

假设我们希望用户以特定格式输入日期,例如“MMM dd, yyyy”。我们可以使用如下模式来检查输入的有效性:

^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d\d?, \d\d\d\d$

(此模式无法检测到日期不合法的情况,但为了示例需要,我们暂且保留它)。

我们希望在用户输入时就使用这个正则表达式进行验证,以便在输入被提交的瞬间(例如用户按错了键)立即报告错误。为此,我们必须区分以下三种情况:

  • 输入不可能与正则表达式匹配;
  • 输入确实与正则表达式匹配;
  • 输入当前虽不匹配该正则表达式,但若继续输入更多字符,最终将匹配该正则表达式。

请注意,这三种情况完全代表了QValidator 的可能状态(参见QValidator::State 枚举)。

特别是在最后一种情况下,我们希望正则表达式引擎报告部分匹配:我们已成功将模式与目标字符串进行匹配,但由于遇到目标字符串的末尾,匹配无法继续。 不过请注意,匹配算法应继续运行并尝试所有可能性;若发现完全(非部分)匹配,则应报告该匹配结果,并将输入字符串视为完全有效。

这种行为由PartialPreferCompleteMatch 匹配类型实现。例如:

QString pattern("^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \\d\\d?, \\d\\d\\d\\d$");
QRegularExpression re(pattern);

QString input("Jan 21,");
QRegularExpressionMatch match = re.match(input, 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

如果将同一正则表达式与目标字符串进行匹配后得到完全匹配,则按常规方式报告该结果:

QString input("Dec 8, 1985");
QRegularExpressionMatch match = re.match(input, 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // true
bool hasPartialMatch = match.hasPartialMatch(); // false

另一个使用不同模式的示例,展示了优先选择完全匹配而非部分匹配的行为:

QRegularExpression re("abc\\w+X|def");
QRegularExpressionMatch match = re.match("abcdef", 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // true
bool hasPartialMatch = match.hasPartialMatch(); // false
QString captured = match.captured(0); // captured == "def"

在此情况下,子模式abc\\w+X 与目标字符串部分匹配;然而,子模式def 与目标字符串完全匹配,因此报告的是完全匹配。

如果在匹配过程中发现了多个部分匹配(但没有完全匹配),则QRegularExpressionMatch 对象将报告第一个被找到的部分匹配。例如:

QRegularExpression re("abc\\w+X|defY");
QRegularExpressionMatch match = re.match("abcdef", 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true
QString captured = match.captured(0); // captured == "abcdef"

增量/多段匹配

增量匹配是部分匹配的另一种应用场景。假设我们要在一篇长文本中查找正则表达式的出现位置(即与该正则表达式匹配的子字符串)。为此,我们需要将长文本以较小的块为单位“喂入”正则表达式引擎。 显而易见的问题是:如果与正则表达式匹配的子字符串跨越了两个或多个片段,该如何处理?

在这种情况下,正则表达式引擎应报告部分匹配,以便我们可以添加新数据后再次进行匹配,并(最终)获得完全匹配。 这意味着正则表达式引擎可能会假设在目标字符串结尾之后还存在其他字符。但这并非字面意义上的——引擎绝不会尝试访问目标字符串最后一个字符之后的任何字符。

QRegularExpression在使用PartialPreferFirstMatch 匹配类型时实现了这种行为。该匹配类型一发现部分匹配便会报告,且不会尝试其他匹配方案(即使这些方案可能导致完全匹配)。例如:

QRegularExpression re("abc|ab");
QRegularExpressionMatch match = re.match("ab", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

这是因为在匹配交替运算符的第一个分支时发现了部分匹配,因此匹配过程随即停止,而不会尝试第二个分支。另一个示例:

QRegularExpression re("abc(def)?");
QRegularExpressionMatch match = re.match("abc", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

这展示了量词的一种看似违反直觉的行为:由于? 是贪婪的,因此引擎在匹配完"abc" 后,会首先尝试继续匹配;但随后匹配到达了被匹配字符串的末尾,因此报告了部分匹配。在下面的例子中,这种现象显得更为出人意料:

QRegularExpression re("(abc)*");
QRegularExpressionMatch match = re.match("abc", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

如果我们记住,引擎期望目标字符串仅是我们要进行匹配的整个文本的一个子字符串(也就是说,正如我们之前所说,引擎假设在目标字符串结尾之后还有其他字符),那么就很容易理解这种行为。

由于* 量词是贪婪的,因此报告完全匹配可能会导致错误,因为在当前主题"abc" 之后,可能还存在其他"abc" 的出现。 例如,完整文本可能是“abcabcX”,因此(在完整文本中)应报告的正确匹配应为"abcabc" ;而仅匹配开头的"abc" ,则会得到一个不完整的匹配结果。

错误处理

由于模式字符串中的语法错误,QRegularExpression 对象可能无效。如果正则表达式有效,isValid() 函数将返回 true,否则返回 false:

QRegularExpression invalidRe("(unmatched|parenthesis");
bool isValid = invalidRe.isValid(); // false

您可以通过调用errorString()函数获取有关具体错误的更多信息;此外,patternErrorOffset()函数将返回模式字符串中的偏移量

QRegularExpression invalidRe("(unmatched|parenthesis");
if (!invalidRe.isValid()) {
    QString errorString = invalidRe.errorString(); // errorString == "missing )"
    int errorOffset = invalidRe.patternErrorOffset(); // errorOffset == 22
    // ...
}

如果尝试使用无效的 QRegularExpression 进行匹配,则返回的QRegularExpressionMatch 对象也将无效(即其isValid() 函数将返回 false)。尝试全局匹配时也是如此。

不受支持的 Perl 兼容正则表达式功能

QRegularExpression 并不支持 Perl 兼容正则表达式中的所有功能。最值得注意的一点是,它不支持捕获组的名称重复,使用重复名称可能会导致未定义的行为。

这一情况可能会在 Qt 的未来版本中发生改变。

调试使用 QRegularExpression 的代码

QRegularExpression 在内部使用即时编译器 (JIT) 来优化匹配算法的执行。JIT 大量使用了自修改代码,这可能会导致 Valgrind 等调试工具崩溃。 若要调试使用 QRegularExpression 的程序,必须启用所有针对自修改代码的检查(例如,Valgrind 的--smc-check 命令行选项)。启用此类检查的缺点是程序运行速度会显著变慢。

为避免这种情况,若在调试模式下编译 Qt,JIT 默认处于禁用状态。您可以通过将QT_ENABLE_REGEXP_JIT 环境变量分别设置为非零值或零值,来覆盖默认设置并启用或禁用 JIT(无论在调试模式还是发布模式下)。

另请参阅 QRegularExpressionMatch 和QRegularExpressionMatchIterator 。

成员类型文档

enum QRegularExpression::MatchOption
flags QRegularExpression::MatchOptions

常数值描述
QRegularExpression::NoMatchOption0x0000未设置任何匹配选项。
QRegularExpression::AnchoredMatchOptionAnchorAtOffsetMatchOption请改用 AnchorAtOffsetMatchOption。
QRegularExpression::AnchorAtOffsetMatchOption0x0001为了使匹配成功,匹配必须精确地从传递给match() 的偏移量处开始,即使模式字符串中不包含任何将匹配锚定在该位置的元字符。 请注意,传递此选项不会将匹配的结束位置锚定到目标字符串的末尾;若要完全锚定正则表达式,请使用anchoredPattern()。此枚举值自 Qt 6.0 起引入。
QRegularExpression::DontCheckSubjectStringMatchOption0x0002在尝试匹配之前,不会检查目标字符串是否符合 UTF-16 规范。使用此选项时请务必格外谨慎,因为尝试匹配无效字符串可能会导致程序崩溃和/或引发安全问题。此枚举值自 Qt 5.4 起引入。

MatchOptions 类型是QFlags<MatchOption> 的 typedef。它存储 MatchOption 值的“或”组合。

enum QRegularExpression::MatchType

MatchType 枚举定义了应针对目标字符串尝试进行的匹配类型。

常量值描述
QRegularExpression::NormalMatch0执行常规匹配。
QRegularExpression::PartialPreferCompleteMatch1将模式字符串与目标字符串进行部分匹配。如果找到部分匹配,则将其记录下来,并照常尝试其他匹配方案。 如果随后找到了完全匹配,则优先采用完全匹配;在这种情况下,仅报告完全匹配。如果未找到完全匹配(而只有部分匹配),则报告部分匹配。
QRegularExpression::PartialPreferFirstMatch2将模式字符串与目标字符串进行部分匹配。若发现部分匹配,则停止匹配并报告该部分匹配结果。在此情况下,不会尝试其他可能导致完全匹配的匹配方案。 此外,此匹配类型假设目标字符串仅是更大文本的一个子字符串,且(在该文本中)目标字符串结尾之后还存在其他字符。这可能会导致出人意料的结果;更多详细信息请参阅partial matching 章节中的讨论。
QRegularExpression::NoMatch3不进行任何匹配。此值由默认构造的 `QRegularExpressionMatch ` 或 `QRegularExpressionMatchIterator` 作为匹配类型返回。由于从未进行过匹配,因此此匹配类型对用户而言实用性不高。该枚举值自 Qt 5.1 起引入。

enum QRegularExpression::PatternOption
flags QRegularExpression::PatternOptions

PatternOption 枚举定义了用于指定模式字符串应如何被解释的修饰符,从而决定了模式与目标字符串的匹配方式。

常量值描述
QRegularExpression::NoPatternOption0x0000未设置任何模式选项。
QRegularExpression::CaseInsensitiveOption0x0001模式应以不区分大小写的方式与目标字符串进行匹配。此选项对应于 Perl 正则表达式中的 /i 修饰符。
QRegularExpression::DotMatchesEverythingOption0x0002模式字符串中的点元字符(. )可以匹配目标字符串中的任何字符,包括换行符(通常,点不会匹配换行符)。此选项对应于 Perl 正则表达式中的/s 修饰符。
QRegularExpression::MultilineOption0x0004模式字符串中的插入符(^ )和美元号($ )元字符,分别允许匹配目标字符串中任何换行符的紧后和紧前位置,以及目标字符串的开头和结尾。此选项对应于 Perl 正则表达式中的/m 修饰符。
QRegularExpression::ExtendedPatternSyntaxOption0x0008模式字符串中未转义且位于字符类之外的任何空白符将被忽略。此外,位于字符类之外的未转义井号(#)会导致其后所有字符(直至第一个换行符,包含该换行符)被忽略。 这既可用于提高模式字符串的可读性,也可在正则表达式中插入注释;当模式字符串是从文件加载或由用户编写时,此功能尤为有用,因为在 C++ 代码中,始终可以利用字符串字面量的规则将注释置于模式字符串之外。 该选项对应于 Perl 正则表达式中的/x 修饰符。
QRegularExpression::InvertedGreedinessOption0x0010量词的贪婪性被反转:* 、+ 、? 、{m,n} 等变为懒惰,而它们的懒惰版本(*? 、+? 、?? 、{m,n}? 等)则变为贪婪。Perl 正则表达式中没有与该选项对应的等效功能。
QRegularExpression::DontCaptureOption0x0020未命名的捕获组不会捕获子字符串;命名的捕获组仍按预期工作,与整个匹配对应的隐式捕获组 0 也是如此。Perl 正则表达式中没有与此选项等效的功能。
QRegularExpression::UseUnicodePropertiesOption0x0040字符类\w 、\d 等,以及其对应类(\W 、\D 等)的含义已从仅匹配 ASCII 字符,更改为匹配具有相应 Unicode 属性的任意字符。 例如,\d 被修改为匹配具有 Unicode Nd(十进制数字)属性的任何字符;\w 被修改为匹配具有 Unicode L(字母)或 N(数字)属性(以及下划线)的任何字符,以此类推。此选项对应于 Perl 正则表达式中的/u 修饰符。

PatternOptions 类型是QFlags<PatternOption> 的 typedef。它存储 PatternOption 值的“或”组合。

[since 6.0] enum QRegularExpression::WildcardConversionOption
flags QRegularExpression::WildcardConversionOptions

WildcardConversionOption 枚举定义了用于修改通配符全局模式转换为正则表达式模式的方式的修饰符。

常量值描述
QRegularExpression::DefaultWildcardConversion0x0未设置任何转换选项。
QRegularExpression::UnanchoredWildcardConversion0x1转换不会将模式锚定。这允许通配符表达式进行部分字符串匹配。
QRegularExpression::NonPathWildcardConversion (since Qt 6.6)0x2转换不会将该模式解释为文件路径通配符。

该枚举在 Qt 6.0 中引入。

WildcardConversionOptions 类型是QFlags<WildcardConversionOption> 的 typedef。它存储 WildcardConversionOption 值的“或”组合。

另请参阅 QRegularExpression::wildcardToRegularExpression 。

成员函数文档

QRegularExpression::QRegularExpression()

创建一个模式为空且不带任何模式选项的 QRegularExpression 对象。

另请参阅 setPattern() 和setPatternOptions()。

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

使用给定的pattern 作为模式,并以options 作为模式选项,构建一个QRegularExpression对象。

另请参阅 setPattern() 和setPatternOptions()。

[noexcept] QRegularExpression::QRegularExpression(const QRegularExpression &re)

创建一个 QRegularExpression 对象,作为re 的副本。

另请参阅 operator=()。

[constexpr noexcept default, since 6.1] QRegularExpression::QRegularExpression(QRegularExpression &&re)

通过从re 移动内容来构造一个QRegularExpression对象。

请注意,被移出的 QRegularExpression 对象只能被销毁或被赋值。调用除析构函数或赋值运算符以外的其他函数,其效果未定义。

该函数在 Qt 6.1 中引入。

另请参阅 operator=()。

[noexcept] QRegularExpression::~QRegularExpression()

销毁QRegularExpression 对象。

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

返回由\A 和\z 锚点包裹的expression ,用于精确匹配。

[static] QString QRegularExpression::anchoredPattern(const QString &expression)

这是一个重载函数。

int QRegularExpression::captureCount() const

返回模式字符串中的捕获组数量;如果正则表达式无效,则返回 -1。

注意: 隐式捕获组 0不包含在返回的数量中。

另请参阅 isValid()。

QString QRegularExpression::errorString() const

返回在检查正则表达式有效性时发现的错误的文本描述;如果未发现错误,则返回“no error”。

另请参阅 isValid() 和patternErrorOffset()。

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

将str 中的所有字符进行转义,使其在用作正则表达式模式字符串时不再具有任何特殊含义,并返回该转义后的字符串。例如:

QString escaped = QRegularExpression::escape("a(x) = f(x) + g(x)");
// escaped == "a\\(x\\)\\ \\=\\ f\\(x\\)\\ \\+\\ g\\(x\\)"

这在从任意字符串构建正则表达式模式时非常方便:

QString pattern = "(" + QRegularExpression::escape(name) +
                "|" + QRegularExpression::escape(nickname) + ")";
QRegularExpression re(pattern);

注意:该 函数实现了 Perl 的 quotemeta 算法,会用反斜杠对str 中的所有字符进行转义,但[A-Z] 、[a-z] 和[0-9] 范围内的字符以及下划线 (_) 字符除外。 与Perl的唯一区别在于,str 中的字面量 NUL 需使用序列"\\0" (反斜杠 +'0' )进行转义,而非"\\\0" (反斜杠 +NUL )。

[static] QString QRegularExpression::escape(const QString &str)

这是一个重载函数。

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

返回正则表达式,其模式为pattern 。如果cs 的值为Qt::CaseSensitive ,则该正则表达式将区分大小写,并根据options 进行转换。

等同于

auto reOptions = cs == Qt::CaseSensitive ? QRegularExpression::NoPatternOption :
                                           QRegularExpression::CaseInsensitiveOption;
return QRegularExpression(wildcardToRegularExpression(str, options), reOptions);

该函数在 Qt 6.0 中引入。

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

尝试对给定的subject 字符串执行正则表达式的全局匹配,从主体中的offset 位置开始,使用matchType 类型的匹配,并遵循给定的matchOptions 。

返回的QRegularExpressionMatchIterator 位于第一个匹配结果(如有)之前。

另请参阅 QRegularExpressionMatchIterator 和global matching 。

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

尝试对给定的subjectView 字符串视图执行正则表达式的全局匹配,从目标字符串中的offset 位置开始,使用matchType 类型的匹配,并遵循给定的matchOptions 。

返回的QRegularExpressionMatchIterator 位于第一个匹配结果(如有)之前。

注意: 只要还有使用该数据的QRegularExpressionMatchIterator 或QRegularExpressionMatch 对象,subjectView 所引用的数据就 必须保持有效。

该函数在 Qt 6.5 中引入。

另请参阅 QRegularExpressionMatchIterator 和global matching 。

bool QRegularExpression::isValid() const

如果正则表达式是有效的(即不包含语法错误等),则返回true ;否则返回 false。使用errorString() 获取错误的文本描述。

另请参阅 errorString() 和patternErrorOffset()。

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

尝试将正则表达式与给定的subject 字符串进行匹配,从主体中的offset 位置开始,使用matchType 类型的匹配,并遵循给定的matchOptions 。

返回的QRegularExpressionMatch 对象包含匹配结果。

另请参阅 QRegularExpressionMatch 和normal matching 。

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

尝试使用正则表达式与给定的subjectView 字符串视图进行匹配,从主体中的offset 位置开始,采用matchType 类型的匹配,并遵循给定的matchOptions 。

返回的QRegularExpressionMatch 对象包含匹配结果。

注意: 只要还有QRegularExpressionMatch 对象在使用它,subjectView 所引用的数据就 必须保持有效。

该函数在 Qt 6.5 中引入。

另请参阅 QRegularExpressionMatch 和normal matching 。

QStringList QRegularExpression::namedCaptureGroups() const

返回一个包含captureCount() + 1个元素的列表,其中包含模式字符串中命名捕获组的名称。该列表按以下规则排序:位于i 位置的列表元素是i 第n个捕获组的名称(如果该捕获组有名称),或者该捕获组未命名时为空字符串。

例如,给定正则表达式

    (?<day>\d\d)-(?<month>\d\d)-(?<year>\d\d\d\d) (\w+) (?<name>\w+)

namedCaptureGroups() 将返回以下列表:

    ("", "day", "month", "year", "", "name")

这反映了以下事实:捕获组 #0(对应整个匹配结果)没有名称,捕获组 #1 的名称为“day”,捕获组 #2 的名称为“month”,以此类推。

如果正则表达式无效,则返回一个空列表。

另请参见 isValid()、QRegularExpressionMatch::captured() 和QString::isEmpty()。

void QRegularExpression::optimize() const

立即编译该模式,包括为优化目的对其进行JIT编译(如果启用了JIT)。

另请参阅 isValid() 和Debugging Code that Uses QRegularExpression 。

QString QRegularExpression::pattern() const

返回正则表达式的模式字符串。

另请参阅 setPattern() 和patternOptions()。

qsizetype QRegularExpression::patternErrorOffset() const

返回在检查正则表达式有效性时,发现错误的模式字符串内的偏移量。如果未发现错误,则返回 -1。

另请参阅 pattern()、isValid() 和errorString()。

QRegularExpression::PatternOptions QRegularExpression::patternOptions() const

返回正则表达式的模式选项。

另请参阅 setPatternOptions() 和pattern()。

void QRegularExpression::setPattern(const QString &pattern)

将正则表达式的模式字符串设置为pattern 。模式选项保持不变。

另请参阅 pattern() 和setPatternOptions()。

void QRegularExpression::setPatternOptions(QRegularExpression::PatternOptions options)

将给定的options 设置为正则表达式的模式选项。模式字符串保持不变。

另请参阅 patternOptions() 和setPattern()。

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

将此正则表达式替换为other 。此操作速度极快,且绝不会失败。

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

返回给定通配符pattern 的正则表达式表示形式。

该函数支持两种转换方式:一种针对文件路径通配符,另一种则更为通用。

默认情况下,该转换针对文件路径通配符,这意味着路径分隔符会受到特殊处理。这表明它不仅仅是将“*”转换为“.*”等简单替换。

QString wildcard = QRegularExpression::wildcardToRegularExpression("*.jpeg");
// Will match files with names like:
//    foo.jpeg
//    f_o_o.jpeg
//    föö.jpeg

通过在转换函数options 中传入NonPathWildcardConversion ,可使用更通用的通配符转换。

此实现严格遵循通配符模式的定义:

c除下文提及的字符外,任何字符均代表其本身。因此,c匹配字符c。
?匹配任何单个字符,但路径分隔符除外(若已选择文件路径通配符功能)。其作用等同于完整正则表达式中的 b{.}。
*匹配零个或多个任意字符,但不包括路径分隔符(若已选中文件路径通配符功能)。这与完整正则表达式中的.*效果相同。
[abc]匹配方括号中给出的任意一个字符。
[a-c]匹配方括号内给定范围中的任意一个字符。
[!abc]匹配括号中未列出的任意一个字符。这与完整正则表达式中的[^abc]效果相同。
[!a-c]匹配一个不属于方括号内给定范围的字符。这与完整正则表达式中的[^a-c]相同。

注意:出于 历史原因,在此语境下反斜杠 (\) 字符不是转义字符。若要匹配特殊字符之一,请将其置于方括号内(例如,[?] )。

有关实现的更多信息,请参阅:

默认情况下,返回的正则表达式是完全锚定的。换言之,无需对结果再次调用anchoredPattern()。若要获取非锚定的正则表达式,请在转换函数options 中传入UnanchoredWildcardConversion 。

另请参阅 escape()。

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

这是一个重载函数。

[noexcept] QRegularExpression &QRegularExpression::operator=(QRegularExpression &&re)

将正则表达式re 通过移动赋值方式赋值给该对象,并返回对结果的引用。模式和模式选项都会被复制。

请注意,被移动的QRegularExpression 只能被销毁或被赋值。调用除析构函数或赋值运算符以外的其他函数,其行为未定义。

[noexcept] QRegularExpression &QRegularExpression::operator=(const QRegularExpression &re)

将正则表达式re 赋值给该对象,并返回该副本的引用。模式和模式选项都会被复制。

相关的非成员

[noexcept] size_t qHash(const QRegularExpression &key, size_t seed = 0)

返回key 的哈希值,并使用seed 作为计算的种子。

[noexcept] bool operator!=(const QRegularExpression &lhs, const QRegularExpression &rhs)

如果正则表达式 `lhs ` 与 `rhs` 不一致,则返回 `true `;否则返回 `false`。

另请参阅 operator==()。

QDataStream &operator<<(QDataStream &out, const QRegularExpression &re)

将正则表达式re 写入流out 。

另请参阅 《Qt 数据类型的序列化》。

QDebug operator<<(QDebug debug, QRegularExpression::PatternOptions patternOptions)

将模式选项 `patternOptions ` 写入调试对象 `debug `,以供调试之用。

另请参阅 “调试技巧”。

QDebug operator<<(QDebug debug, const QRegularExpression &re)

将正则表达式re 写入调试对象debug ,以供调试之用。

另请参阅 《调试技巧》。

[noexcept] bool operator==(const QRegularExpression &lhs, const QRegularExpression &rhs)

如果正则表达式 `lhs ` 与 `rhs` 相等,则返回 `true `;否则返回 `false`。两个 `QRegularExpression ` 对象若具有相同的模式字符串和相同的模式选项,则被视为相等。

另请参阅 operator!=()。

QDataStream &operator>>(QDataStream &in, QRegularExpression &re)

从流in 读取正则表达式,并将其写入re 。

另请参阅 《Qt 数据类型的序列化》。

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