Класс QRegularExpression

Класс QRegularExpression предоставляет сопоставление с образцом с использованием регулярных выражений. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются повторно входящими.

Открытые типы

Общедоступные функции

Статические общедоступные члены

Связанные свободные функции

Подробное описание

Регулярные выражения, или regexp, представляют собой очень мощный инструмент для работы со строками и текстами. Это полезно во многих контекстах, например:

Этот документ отнюдь не является полным справочником по сопоставлению шаблонов с помощью регулярных выражений, и следующие разделы потребуют от читателя некоторых базовых знаний о регулярных выражениях, похожих на Perl, и их синтаксисе шаблонов.

Хорошие справочные материалы по регулярным выражениям включают:

• Mastering Regular Expressions (Третье издание) Джеффри Э. Ф. Фридла, 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);

В качестве альтернативы можно использовать функцию setPatternOptions() для существующего объекта QRegularExpression:

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

Получить параметры шаблона, установленные для объекта QRegularExpression, можно с помощью функции patternOptions():

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-й группой захвата:

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() для получения следующего результата без перемещения итератора.

Также можно просто использовать результат QRegularExpression::globalMatch в цикле for с диапазоном, например, так:

// 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. Если найдено частичное совпадение, то вызов функции hasMatch() для объекта QRegularExpressionMatch, возвращаемого функцией match(), вернёт 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 (just-in-time) для оптимизации выполнения алгоритма сопоставления. JIT активно использует самомодифицируемый код, что может привести к зависанию таких средств отладки, как Valgrind. Если вы хотите отладить программы, использующие QRegularExpression, необходимо включить все проверки самомодифицируемого кода (например, опция командной строки Valgrind --smc-check). Недостатком включения таких проверок является значительное замедление работы вашей программы.

Чтобы избежать этого, JIT по умолчанию отключен при компиляции Qt в отладочном режиме. Можно переопределить значение по умолчанию и включить или выключить использование JIT (как в отладочном, так и в релизном режиме), установив переменную окружения QT_ENABLE_REGEXP_JIT соответственно на ненулевое или нулевое значение.

См. также QRegularExpressionMatch и QRegularExpressionMatchIterator.

Документация по типам элементов

перечисление QRegularExpression::MatchOptionфлаги QRegularExpression::MatchOptions

Тип MatchOptions — это псевдоним для QFlags<MatchOption>. Он хранит логическое ИЛИ сочетание значений MatchOption.

перечисление QRegularExpression::MatchType

Перечисление MatchType определяет тип сопоставления, которое должно быть выполнено со строкой-субъектом.

enum QRegularExpression::PatternOptionflags QRegularExpression::PatternOptions

Перечисление PatternOption определяет модификаторы способа интерпретации строки-шаблона и, следовательно, способа сопоставления шаблона с целевой строкой.

Тип PatternOptions является псевдонимом для QFlags<PatternOption>. Он хранит логическое ИЛИ комбинацию значений PatternOption.

[since 6.0] enum QRegularExpression::WildcardConversionOptionflags QRegularExpression::WildcardConversionOptions

Перечисление WildcardConversionOption определяет модификаторы способа преобразования шаблона подстановок в шаблон регулярного выражения.

Это перечисление было введено или изменено в Qt 6.0.

Тип WildcardConversionOptions является псевдонимом для QFlags<WildcardConversionOption>. Он хранит логическое ИЛИ комбинацию значений WildcardConversionOption.

Документация по членам-функциям

[since 6.1] QRegularExpression::QRegularExpression(QRegularExpression &&re)

Конструирует объект QRegularExpression, перемещая данные из re.

Обратите внимание, что перемещённый из QRegularExpression объект может быть только уничтожен или присвоен. Эффект вызова других функций, кроме деструктора или одного из операторов присваивания, не определён.

Эта функция была введена в Qt 6.1.

См. также operator=().

QRegularExpression::QRegularExpression(const QRegularExpression &re)

Конструирует объект QRegularExpression как копию объекта re.

См. также operator=().

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

Конструирует объект QRegularExpression, используя заданный pattern как шаблон и options как параметры шаблона.

См. также setPattern() и setPatternOptions().

QRegularExpression::QRegularExpression()

Конструирует объект QRegularExpression с пустым шаблоном и без параметров шаблона.

См. также setPattern() и setPatternOptions().

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

Перемещает присваивание регулярного выражения re в этот объект и возвращает ссылку на результат. Как шаблон, так и параметры шаблона копируются.

Обратите внимание, что перемещённый из QRegularExpression объект может быть только уничтожен или присвоен. Эффект вызова других функций, кроме деструктора или одного из операторов присваивания, не определён.

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

Присваивает регулярное выражение re этому объекту и возвращает ссылку на копию. Как шаблон, так и параметры шаблона копируются.

QRegularExpression::~QRegularExpression()

Уничтожает объект QRegularExpression.

[static, since 5.15] QString QRegularExpression::anchoredPattern(QStringView expression)

Возвращает expression, заключённую между анкерами \A и \z, для использования в точном сопоставлении.

Эта функция была введена в Qt 5.15.

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

Это перегруженный метод.

Этот метод был представлен в Qt 5.12.

int QRegularExpression::captureCount() const

Возвращает количество захватывающих групп внутри строки шаблона или -1, если регулярное выражение некорректно.

Примечание: Неявная захватывающая группа 0 не включается в возвращаемое число.

См. также isValid().

QString QRegularExpression::errorString() const

Возвращает текстовое описание ошибки, обнаруженной при проверке корректности регулярного выражения, или «нет ошибки», если ошибок не обнаружено.

См. также isValid() и patternErrorOffset().

[static, since 5.15] 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's quotemeta и экранирует все символы в str с помощью обратного слэша, за исключением символов в диапазонах [A-Z], [a-z] и [0-9], а также символа подчёркивания (_). Единственное отличие от Perl заключается в том, что буквальный NUL внутри str экранируется последовательностью "\\0" (обратный слэш + '0'), вместо "\\\0" (обратный слэш + NUL).

Этот метод был представлен в Qt 5.15.

[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. Регулярное выражение будет чувствительным к регистру, если 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 расположен перед первым результатом совпадения (если таковой имеется).

Примечание: Данные, на которые ссылается subject, должны оставаться валидными до тех пор, пока существуют объекты QRegularExpressionMatch, использующие их. В настоящее время Qt делает (поверхностную) копию данных, но это поведение может измениться в будущих версиях Qt.

См. также QRegularExpressionMatchIterator и глобальный поиск.

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

Это перегруженный метод.

Попытка выполнить глобальный поиск по регулярному выражению в заданном представлении строки subjectView, начиная с позиции offset, используя тип сопоставления matchType и учитывая заданные matchOptions.

Возвращаемый QRegularExpressionMatchIterator расположен перед первым результатом совпадения (если таковой имеется).

Примечание: Данные, на которые ссылается subjectView, должны оставаться валидными до тех пор, пока существуют объекты QRegularExpressionMatchIterator или QRegularExpressionMatch, использующие их.

Этот метод был представлен в Qt 6.0.

См. также 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

Попытка сопоставить регулярное выражение с заданной строкой subject, начиная с позиции offset, используя тип сопоставления matchType и учитывая заданные matchOptions.

Возвращаемый объект QRegularExpressionMatch содержит результаты сопоставления.

Примечание: Данные, на которые ссылается subject, должны оставаться валидными до тех пор, пока существуют объекты QRegularExpressionMatch, использующие их. В настоящее время Qt делает (поверхностную) копию данных, но это поведение может измениться в будущих версиях Qt.

См. также QRegularExpressionMatch и нормальное сопоставление.

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

Это перегруженный метод.

Попытка сопоставить регулярное выражение с заданным представлением строки subjectView, начиная с позиции offset, используя тип сопоставления matchType и учитывая заданные matchOptions.

Возвращаемый объект QRegularExpressionMatch содержит результаты сопоставления.

Примечание: Данные, на которые ссылается subjectView, должны оставаться валидными до тех пор, пока существуют объекты QRegularExpressionMatch.

Этот метод был представлен в Qt 6.0.

См. также QRegularExpressionMatch и нормальное сопоставление.

[since 5.1] 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» и т.д.

Если регулярное выражение некорректно, возвращает пустой список.

Этот метод был представлен в Qt 5.1.

См. также isValid(), QRegularExpressionMatch::captured() и QString::isEmpty().

[since 5.4] void QRegularExpression::optimize() const

Компилирует шаблон немедленно, включая JIT-компиляцию (если JIT включен) для оптимизации.

Этот метод был представлен в Qt 5.4.

См. также 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().

void QRegularExpression::swap(QRegularExpression &other)

Меняет местами регулярное выражение other с этим регулярным выражением. Эта операция очень быстрая и никогда не терпит неудачу.

[static, since 5.15] 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

По умолчанию возвращаемое регулярное выражение полностью закреплено. Другими словами, нет необходимости вызывать anchoredPattern() снова на результате. Чтобы получить регулярное выражение, которое не закреплено, передайте UnanchoredWildcardConversion в качестве параметров преобразования options.

Эта реализация тесно следует определению шаблона для шаблонов glob:

Примечание: Символ обратной косой черты (\) не является символом-модификатором в этом контексте. Чтобы сопоставить один из специальных символов, поместите его в квадратные скобки (например, [?]).

Дополнительную информацию об реализации можно найти по ссылкам:

• Статья Википедии о glob
• man 7 glob

Эта функция была добавлена в Qt 5.15.

См. также escape().

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

Это перегруженная функция.

Эта функция была добавлена в Qt 5.12.

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

Возвращает true если регулярное выражение отличается от re, в противном случае возвращает false.

См. также operator==().

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

Возвращает true если регулярное выражение равно re, в противном случае возвращает false. Два объекта QRegularExpression равны, если у них одинаковая строка шаблона и одинаковые параметры шаблона.

См. также operator!=().