QRegularExpression Class

QRegularExpression 类使用正则表达式进行模式匹配。更多

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

该类可等价比较

注意:该类中的所有函数都是可重入的

公共类型

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 是处理字符串和文本的强大工具。这在很多情况下都非常有用,例如

验证regexp 可以测试子串是否符合某些条件,例如是否是整数或是否不包含空白。
搜索与简单的子字符串匹配相比,regexp 提供了更强大的模式匹配功能,例如,匹配maillettercorrespondence 中的一个单词,但不匹配emailmailman、 mailerletterbox 等单词。
搜索和替换regexp 可以用不同的子串替换所有出现的子串,例如,用&amp;替换所有出现的&,除非&后面已经有amp;
字符串分割regexp 可用于识别字符串应分割的位置,例如分割以制表符分隔的字符串。

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

有关正则表达式的参考文献包括

简介

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

你可以通过向 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 返回 ,它是一个类似 Java 的正向迭代器,可用于遍历结果。例如QRegularExpressionMatchIterator

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::matchQRegularExpression::globalMatch 时,必须通过指定PartialPreferCompleteMatchPartialPreferFirstMatch 的匹配类型来明确请求部分匹配。如果找到了部分匹配,那么在match() 返回的QRegularExpressionMatch 对象上调用hasMatch() 函数将返回false ,但hasPartialMatch() 将返回true

当发现部分匹配时,不会返回捕获的子字符串,与整个匹配对应的(隐式)捕获组 0 会捕获主题字符串中部分匹配的子字符串。

请注意,如果找到了部分匹配,请求部分匹配仍可能导致完全匹配;在这种情况下,hasMatch() 将返回truehasPartialMatch() 将返回falseQRegularExpressionMatch 不会同时报告部分匹配和完全匹配。

部分匹配主要在两种情况下有用:实时验证用户输入和增量/多分段匹配。

验证用户输入

假设我们希望用户以特定格式输入日期,例如 "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"

增量/多部分匹配

增量匹配是部分匹配的另一种用法。假设我们要查找大段文本中正则表达式的出现次数(即匹配正则表达式的子串)。为此,我们希望将大段文本分成小块 "喂给 "正则表达式引擎。显而易见的问题是,如果与正则表达式相匹配的子串跨越了两块或多块文本,该怎么办?

在这种情况下,正则表达式引擎应该报告部分匹配,这样我们就可以再次添加新数据进行匹配,(最终)获得完整的匹配。这意味着正则表达式引擎可能会假定主题字符串末尾之外还有其他字符。这并不是字面上的意思--引擎永远不会尝试访问主题中最后一个字符之后的任何字符。

当使用PartialPreferFirstMatch 匹配类型时,QRegularExpression 会实现这种行为。这种匹配类型会在发现部分匹配时立即报告,而不会尝试其他匹配选项(即使这些选项可能导致完全匹配)。例如

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 兼容正则表达式的所有功能。最值得注意的是,QRegularExpression 不支持捕获组的重复名称,使用这些名称可能会导致未定义的行为。

这可能会在 Qt 的未来版本中有所改变。

调试使用 QRegularExpression 的代码

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

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

另请参见 QRegularExpressionMatchQRegularExpressionMatchIterator

成员类型文档

枚举 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> 的类型定义。它存储 MatchOption 值的 OR 组合。

enum QRegularExpression::MatchType

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

常量描述
QRegularExpression::NormalMatch0正常匹配。
QRegularExpression::PartialPreferCompleteMatch1模式字符串与主题字符串进行部分匹配。如果发现了部分匹配,则将其记录下来,并像往常一样尝试其他匹配选项。如果找到完全匹配,则优先于部分匹配;在这种情况下,只报告完全匹配。如果没有找到完全匹配(只有部分匹配),则报告部分匹配。
QRegularExpression::PartialPreferFirstMatch2模式字符串与主题字符串部分匹配。如果找到部分匹配,则停止匹配并报告部分匹配。在这种情况下,不会尝试其他匹配选项(可能导致完全匹配)。此外,这种匹配类型假定主题字符串只是更大文本的一个子串,而且(在该文本中)主题字符串末尾之外还有其他字符。这可能会导致令人惊讶的结果;详情请参见partial matching 部分的讨论。
QRegularExpression::NoMatch3不进行匹配。默认构造QRegularExpressionMatchQRegularExpressionMatchIterator 将此值作为匹配类型返回。使用这种匹配类型对用户来说用处不大,因为根本不会发生匹配。Qt 5.1 引入了该枚举值。

枚举 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> 的类型定义。它存储 PatternOption 值的 OR 组合。

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

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

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

该枚举在 Qt 6.0 中引入。

WildcardConversionOptions 类型是QFlags<WildcardConversionOption> 的类型定义。它存储 WildcardConversionOption 值的 OR 组合。

另请参阅 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=().

[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 锚点之间的expression ,用于精确匹配。

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

这是一个重载函数。

int QRegularExpression::captureCount() const

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

注意: 隐式捕获组 0包括在返回的个数中。

另请参阅 isValid()。

QString QRegularExpression::errorString() const

返回检查正则表达式有效性时发现的错误的文字说明,如果没有发现错误,则返回 "无错误"。

另请参见 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)

返回 glob 模式的正则表达式pattern 。如果csQt::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 位于第一个匹配结果(如果有)之前。

另请参阅 QRegularExpressionMatchIteratorglobal 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 位于第一个匹配结果(如果有)之前。

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

此函数在 Qt 6.5 中引入。

另请参阅 QRegularExpressionMatchIteratorglobal 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 对象包含匹配结果。

另请参阅 QRegularExpressionMatchnormal 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 中引入。

另请参阅 QRegularExpressionMatchnormal matching

QStringList QRegularExpression::namedCaptureGroups() const

返回包含captureCount() + 1 个元素的列表,其中包含模式字符串中已命名捕获组的名称。列表排序为:如果i-th 捕捉组有名称,则位于i 位置的元素为该捕捉组的名称;如果捕捉组未命名,则为空字符串。

例如,给定正则表达式

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

namedCaptureGroups() 将返回以下列表:

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

对应的事实是捕获组 #0(对应整个匹配)没有名称,捕获组 #1 的名称是 "日",捕获组 #2 的名称是 "月",等等。

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

另请参阅 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)

返回给定 globpattern 的正则表达式。

有两种可能的转换,一种是针对文件路径的钩选,另一种是更通用的钩选。

默认情况下,转换针对的是文件路径嵌套,这尤其意味着路径分隔符会得到特殊处理。这意味着它不仅仅是从 "*"到".*"的基本转换。

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

通过在转换options 中传递NonPathWildcardConversion ,可以实现更通用的套码转换。

该实现与 glob 模式的通配符定义密切相关:

c除下面提到的字符外,任何字符都代表自己。因此,c与字符c 匹配。
?匹配任何单字符,路径分隔符除外(如果选择了文件路径全局搜索)。它与完整 regexps 中的 b{.} 相同。
*匹配零个或多个任意字符,路径分隔符除外(如果选择了文件路径屏蔽)。它与完整 regexps 中的.*相同。
[abc]匹配括号中的一个字符。
[a-c]匹配括号中给定范围内的一个字符。
[! abc] 匹配括号中未给出的一个字符。匹配括号中未给出的一个字符。它与完整 regexp 中的[^abc]相同。
[a-c]匹配括号中未给出范围的一个字符。它与完整 regexp 中的[^a-c]相同。

注意: 由于历史原因,反斜杠 (\) 字符在这里不是转义字符。为了匹配其中一个特殊字符,请将其放在方括号中(例如,[?] )。

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

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

另请参见 escape()。

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

这是一个重载函数。

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

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

请注意,moved-fromQRegularExpression 只能被销毁或赋值。调用析构函数或赋值操作符之外的其他函数的效果是未定义的。

[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 数据类型

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