QRegularExpression 类

QRegularExpression 类提供了使用正则表达式进行模式匹配的功能。 了解更多...

头文件 #include <QRegularExpression>
CMakefind_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmakeQT += core

注意： 此类中所有函数都是 可重入的。

公共类型

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

公共函数

QRegularExpression()
QRegularExpression(const QString &pattern, QRegularExpression::PatternOptions options = NoPatternOption)
QRegularExpression(const QRegularExpression &re)
(since 6.1) QRegularExpression(QRegularExpression &&re)
~QRegularExpression()
intcaptureCount() const
QStringerrorString() const
QRegularExpressionMatchIteratorglobalMatch(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
(since 6.5) QRegularExpressionMatchIteratorglobalMatchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
boolisValid() const
QRegularExpressionMatchmatch(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
(since 6.5) QRegularExpressionMatchmatchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
QStringListnamedCaptureGroups() const
voidoptimize() const
QStringpattern() const
qsizetypepatternErrorOffset() const
QRegularExpression::PatternOptionspatternOptions() const
voidsetPattern(const QString &pattern)
voidsetPatternOptions(QRegularExpression::PatternOptions options)
voidswap(QRegularExpression &other)
booloperator!=(const QRegularExpression &re) const
QRegularExpression &operator=(const QRegularExpression &re)
QRegularExpression &operator=(QRegularExpression &&re)
booloperator==(const QRegularExpression &re) const

静态公共成员

QStringanchoredPattern(QStringView expression)
QStringanchoredPattern(const QString &expression)
QStringescape(QStringView str)
QStringescape(const QString &str)
(自 6.0) QRegularExpressionfromWildcard(QStringView pattern, Qt::CaseSensitivity cs = Qt::CaseInsensitive, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
QStringwildcardToRegularExpression(QStringView pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
QStringwildcardToRegularExpression(const QString &pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
size_tqHash(const QRegularExpression &key, size_t seed = 0)
QDataStream &operator<<(QDataStream &out, const QRegularExpression &re)
QDebugoperator<<(QDebug debug, const QRegularExpression &re)
QDebugoperator<<(QDebug debug, QRegularExpression::PatternOptions patternOptions)
QDataStream &operator>>(QDataStream &in, QRegularExpression &re)

详细信息

正则表达式，或简称“正则”，是一种处理字符串和文本的非常强大的工具。这在许多场景中都很适用，例如：

验证正则表达式可以检测子串是否符合某些条件，例如是否是整数或不包含空格。
搜索正则表达式提供的模式匹配功能比简单的子串匹配更强大，例如，匹配“mail”、“letter”或“correspondence”中的任何一个单词，但不能匹配“email”、“mailman”、“mailer”、“letterbox”等单词。
搜索和替换正则表达式可以替换所有匹配的子串，例如，将所有的“&”替换为“&”，但已由“amp;”跟随的“&”除外。
字符串分割可以使用正则表达式来确定字符串应该在哪里分割，例如，分隔制表符分隔的字符串。

本文件绝不仅仅是对使用正则表达式进行模式匹配的完整参考，以下部分将要求读者具备一些类似Perl的正则表达式及其模式语法的基本知识。

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

  • 精通正则表达式》（第3版） - Jeffrey E. F. Friedl 著，ISBN 0-596-52812-4；
  • pcrepattern(3) 手册页，描述了PCRE（Perl兼容正则表达式的参考实现）所支持的模式语法；
  • Perl的正则表达式文档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 匹配类型来选择的（默认）。也可以启用正则表达式对主体字符串的局部匹配：更多详细信息请参阅局部匹配 部分。

匹配选项是一组一个或多个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来检索匹配整个模式所对应的子字符串（还可以参考提取捕获子字符串那一节）

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-th捕获组捕获的字符串

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()函数中正常匹配时一样。

部分匹配

当达到主字符串的结尾时，获得部分匹配，但需要更多的字符才能成功完成匹配。请注意，部分匹配通常比正常匹配低效得多，因为许多匹配算法的优化都无法使用。

在调用时节时，必须显式请求部分匹配，指定匹配类型为PartialPreferCompleteMatch或PartialPreferFirstMatch。如果找到部分匹配，则调用QRegularExpression::match或QRegularExpression::globalMatch返回的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。

成员类型文档

枚举 QRegularExpression::MatchOption
标记 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值的逻辑或组合。

枚举 QRegularExpression::MatchType

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

常量值描述
QRegularExpression::NormalMatch0执行正常的匹配。
QRegularExpression::PartialPreferCompleteMatch1模式字符串会被部分地与主题字符串匹配。如果找到部分匹配，则将其记录下来，然后尝试其他匹配选项。如果然后找到完全匹配，则将其优先于部分匹配；在这种情况下，只报告完全匹配。如果未找到完全匹配（但只有部分匹配），则报告部分匹配。
QRegularExpression::PartialPreferFirstMatch2模式字符串部分匹配主字符串。如果找到部分匹配，则匹配停止并报告部分匹配。在这种情况下，不会尝试其他匹配备选项（可能导致完整匹配）。此外，此匹配类型假定主字符串仅是大文本的一个子字符串，并且（在此文本中）主字符串结束时还有其他字符。这可能导致意外结果；更多详情请参阅部分匹配部分。
QRegularExpression::NoMatch3未执行匹配。默认构造的QRegularExpressionMatch或QRegularExpressionMatchIterator返回此匹配类型。使用此匹配类型对用户来说不是非常有用，因为根本不会发生匹配。此枚举值自Qt 5.1引入。

枚举 QRegularExpression::PatternOption
标志 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> 的别名。它存储了一个PatternOption值或的组合。

[since 6.0] 枚举 QRegularExpression::WildcardConversionOption
flags QRegularExpression::WildcardConversionOptions

WildcardConversionOption 枚举定义了对通配符glob模式转换为正则表达式模式的修改器。

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

此枚举在Qt 6.0中引入。

WildcardConversionOptions 类型是 QFlags<WildcardConversionOption> 的别名。它存储了一个WildcardConversionOption值的或组合。

另请参阅 QRegularExpression::wildcardToRegularExpression.

成员函数文档

QRegularExpression::QRegularExpression()

使用空模式和没有模式选项构造一个QRegularExpression对象。

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

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

使用给定的 pattern 作为模式和 options 作为模式选项来构造一个QRegularExpression对象。

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

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

构造一个QRegularExpression对象，将其作为 re 的副本。

另请参阅 operator=().

[noexcept, 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 锚点之间的 表达式，用于精确匹配。

[静态] QString QRegularExpression::anchoredPattern(const QString &expression)

这是一个重载函数。

int QRegularExpression::captureCount() const

返回模式字符串中的括号组数，如果正则表达式无效，则返回-1。

注意：隐式括号组0不包括在返回的数字中。

另请参阅：isValid()。

QString QRegularExpression::errorString() const

返回在检查正则表达式有效性时找到的错误描述文本，如果没有找到错误，则返回“没有错误”。

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

[静态] 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）。

[静态] QString QRegularExpression::escape(const QString &str)

这是一个重载函数。

[静态，自6.0版本起] QRegularExpression QRegularExpression::fromWildcard(QStringView pattern, Qt::CaseSensitivity cs = Qt::CaseInsensitive, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)

返回glob模式 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和全局匹配。

[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位于第一个匹配结果之前（如果有）。

注意：subjectView引用的数据必须在还有使用它的QRegularExpressionMatchIterator或QRegularExpressionMatch对象时保持有效。

此函数在Qt 6.5中引入。

另请参阅QRegularExpressionMatchIterator和全局匹配。

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

尝试从主体的位置offset开始匹配给定的subject字符串，使用类型为matchType的匹配并进行相应的matchOptions设置。

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

另请参阅QRegularExpressionMatch和正常匹配。

[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对象包含匹配的结果。

注意事项：只要还有使用 subjectView 的 QRegularExpressionMatch 对象，引用 subjectView 的数据必须保持有效。

此函数在Qt 6.5中引入。

另请参阅QRegularExpressionMatch和正常匹配。

QStringList QRegularExpression::namedCaptureGroups() const

返回一个包含 captureCount() + 1 个元素的列表，包含模式字符串中命名捕获组的名称。列表按顺序排列，使得列表位置 i 的元素是第 i 个捕获组的名称，如果它有名称，或者如果该捕获组无名称，则为空字符串。

例如，给定以下正则表达式

    (?<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() 和 调试使用 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)

返回给定 glob pattern 的正则表达式表示。

可能有两种转换，一种针对文件路径 glob，另一种更为通用。

默认情况下，转换针对文件路径 glob，这意味着路径分隔符会受到特殊处理。这意味着不仅仅是将 "*" 转换为 ".*" 等操作。

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

通过在转换 options 中传递 NonPathWildcardConversion，可以获得更通用的 globbing 转换。

此实现严格遵循 glob 模式定义中的通配符。

c任何字符除了以下提到的字符外，都表示自身。因此 c 匹配字符 c。
?匹配任何单个字符，除非是路径分隔符（如果已选择文件路径 glob）。它等同于全正则表达式中的 b{.}。
*匹配零个或多个任何字符，除非是路径分隔符（如果已选择文件路径 glob）。它等同于全正则表达式中的 .*。
[abc]匹配括号中的字符。
[a-c]匹配括号中给定范围内的字符。
[!abc]匹配括号中未给出的字符。它等同于全正则表达式中的 [^abc]。
[!a-c]匹配括号中不在给定范围内的字符。它等同于全正则表达式中的 [^a-c]。

注意： 出于历史原因，反斜杠 (\) 字符在此上下文中不是转义字符。要匹配特殊字符之一，请将其放在方括号内（例如，[?]）。

有关实现的信息，请参阅

默认情况下，返回的正则表达式是完整锚定的。换句话说，无需再次调用 anchoredPattern()。要获取未锚定的正则表达式，请在转换 options 中传递 UnanchoredWildcardConversion。

另请参阅 escape。

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

这是一个重载函数。

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

如果正则表达式与re不同，则返回真，否则返回假。

另请参阅operator==().

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

将正则表达式re分配给此对象，并返回副本的引用。模式以及模式选项都将复制。

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

将正则表达式re移位分配给此对象，并返回结果的引用。模式和模式选项都将复制。

请注意，已移除的QRegularExpression只能被销毁或分配。调用析构函数或赋值运算符之外的函数的效果是未定义的。

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

如果正则表达式与re相等，则返回真，否则返回假。如果两个QRegularExpression对象具有相同的模式字符串和相同的模式选项，则它们是相等的。

另请参阅operator!=().

相关非成员

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

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

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

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

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

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

将正则表达式re写入调试对象debug以进行调试。

另请参阅调试技术。

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

将模式选项patternOptions写入调试对象debug以进行调试。

另请参阅调试技术。

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

从流in中读取正则表达式到re。

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

© 2024 Qt公司。包含在此的文档贡献是各自所有者的版权。提供的文档是根据自由软件基金会发布并由其出版的GNU自由文档许可证版本1.3许可的。Qt及其相应商标是芬兰Qt公司及其全球其他国家的商标。所有其他商标均为其各自所有者的财产。