Класс QRegularExpression

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

Этот класс был введён в Qt 5.0.

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

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

Типы public

Функции public

Статические public члены

Связанные Нечленные Элементы

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

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

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

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

• Мастерство регулярных выражений (Третье издание) Джеффри Э. Ф. Фридл, ISBN 0-596-52812-4;
• страница руководства pcrepattern(3), описывающая синтаксис шаблонов, поддерживаемый PCRE (реализацией регулярных выражений, совместимых с Perl);
• документация Perl по регулярным выражениям http://perldoc.perl.org/perlre.html и учебник Perl по регулярным выражениям http://perldoc.perl.org/perlretut.html.

Введение

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("\\\\");

Функция 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() для существующего объекта QRegularExpressionObject:

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

Можно передать начальное смещение и одну или несколько опций сопоставления в функцию 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.

Примечания для пользователей QRegExp

Класс QRegularExpression, представленный в Qt 5, является значительным улучшением по сравнению с QRegExp с точки зрения предлагаемых API, поддерживаемого синтаксиса шаблонов и скорости выполнения. Самое большое различие заключается в том, что QRegularExpression просто хранит регулярное выражение, и оно не изменяется при запросе сопоставления. Вместо этого возвращается объект QRegularExpressionMatch для проверки результата сопоставления и извлечения подстроки захвата. То же самое относится к глобальному сопоставлению и QRegularExpressionMatchIterator.

Другие отличия описаны ниже.

Перенос из QRegExp::exactMatch()

QRegExp::exactMatch() в Qt 4 выполняла две задачи: точно сопоставляла регулярное выражение со строкой-предметом и реализовывала частичное сопоставление.

Перенос из точного сопоставления QRegExp

Точное сопоставление указывает, соответствует ли регулярное выражение всей строке-предмету. Например, классы создают вывод по строке-предмету "abc123":

Точное сопоставление не отражается в QRegularExpression. Если вы хотите убедиться, что строка-предмет точно соответствует регулярному выражению, вы можете заключить шаблон в пару выражений привязки. В большинстве случаев достаточно просто поместить шаблон между ^ и $ якорями:

QRegularExpression re("^this pattern must match exactly$");

Однако помните, что якорь $ соответствует не только концу строки, но также и символу новой строки прямо перед концом строки; то есть, предыдущий шаблон соответствует строке «this pattern must match exactly\n». Кроме того, поведение обоих якорей ^ и $ изменяется, если параметр MultiLineOption установлен явно (как параметр шаблона) или неявно (как директива внутри строки шаблона).

Поэтому в общем случае вы должны заключить шаблон в \A и \z якоря:

QString p("a .*|pattern");
QRegularExpression re("\\A(?:" + p + ")\\z"); // re matches exactly the pattern string p

Обратите внимание на использование незахватывающей группы для сохранения смысла оператора ветвления внутри шаблона.

Вспомогательный метод QRegularExpression::anchoredPattern() делает это за вас.

Перенос частичного сопоставления из QRegExp

При использовании QRegExp::exactMatch(), если точное совпадение не найдено, можно узнать, сколько символов строки-предмета было сопоставлено с регулярным выражением, вызвав QRegExp::matchedLength(). Если возвращённая длина равна длине строки-предмета, можно сделать вывод о том, что найдено частичное совпадение.

QRegularExpression поддерживает частичное сопоставление явно с помощью соответствующего типа MatchType.

Глобальное сопоставление

Из-за ограничений API QRegExp невозможно правильно реализовать глобальное сопоставление (то есть, как в Perl). В частности, шаблоны, которые могут соответствовать 0 символам (например, "a*" ), представляют проблему.

QRegularExpression::globalMatch() правильно реализует глобальное сопоставление Perl, и возвращаемый итератор можно использовать для проверки каждого результата.

Поддержка свойств Юникода

При использовании QRegExp классы символов, такие как \w, \d, и т.д., соответствуют символам с соответствующим свойством Юникода: например, \d соответствует любому символу со свойством Юникода Nd (десятичный цифровой).

Эти классы символов по умолчанию соответствуют только символам ASCII при использовании QRegularExpression: например, \d точно соответствует символу в диапазоне 0-9 ASCII. Можно изменить это поведение, используя параметр шаблона UseUnicodePropertiesOption.

Сопоставление с подстановкой

Нет прямого способа выполнить сопоставление с подстановкой в QRegularExpression. Однако, предоставлен метод wildcardToRegularExpression для преобразования шаблонов glob в Perl-совместимое регулярное выражение, которое можно использовать для этой цели.

Другие синтаксисы шаблонов

QRegularExpression поддерживает только Perl-совместимые регулярные выражения.

Минимальное сопоставление

QRegExp::setMinimal() реализовывало минимальное сопоставление, просто перевернув жадность квантификаторов (QRegExp не поддерживал ленивых квантификаторов, таких как *?, +?, и т.д.). QRegularExpression поддерживает жадные, ленивые и поглощающие квантификаторы. Вспомогательный параметр шаблона InvertedGreedinessOption может пригодиться для эмуляции эффектов QRegExp::setMinimal(): при включении он инвертирует жадность квантификаторов (жадные становятся ленивыми и наоборот).

Режимы якорей

Параметр сопоставления AnchoredMatchOption можно использовать для эмуляции поведения QRegExp::CaretAtOffset. Нет эквивалента для других режимов QRegExp::CaretMode.

Отладка кода, использующего QRegularExpression

QRegularExpression внутренне использует компилятор в реальном времени (JIT) для оптимизации выполнения алгоритма сопоставления. JIT использует самомодифицирующийся код, что может привести к аварийному завершению инструментов отладки, таких как Valgrind. Вам необходимо включить все проверки самомодифицирующегося кода, если вы хотите отладить программы, использующие QRegularExpression (например, см. опцию командной строки Valgrind --smc-check ). Недостатком включения таких проверок является значительное замедление работы программы.

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

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

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

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

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

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

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

перечисление QRegularExpression::PatternOptionфлаги QRegularExpression::PatternOptions

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

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

Документация функций членов

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::operator=(const QRegularExpression &re)

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

QRegularExpression::~QRegularExpression()

Удаляет объект QRegularExpression.

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

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

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

См. также Перенос из точного соответствия QRegExp.

int QRegularExpression::captureCount() const

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

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

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

QString QRegularExpression::errorString() const

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

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

[static] QString QRegularExpression::escape(const QString &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).

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

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

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

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

QRegularExpressionMatchIterator QRegularExpression::globalMatch(const QStringRef &subjectRef, int offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const

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

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

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

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

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

bool QRegularExpression::isValid() const

Возвращает true если регулярное выражение является корректным регулярным выражением (то есть не содержит синтаксических ошибок и т. п.), в противном случае — false. Используйте errorString() для получения текстового описания ошибки.

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

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

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

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

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

QRegularExpressionMatch QRegularExpression::match(const QStringRef &subjectRef, int offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const

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

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

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

Эта функция была добавлена в Qt 5.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 есть имя "день", у захватывающей группы #2 есть имя "месяц" и т. д.

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

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

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

void QRegularExpression::optimize() const

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

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

См. также isValid() и Отладка кода, использующего QRegularExpression.

QString QRegularExpression::pattern() const

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

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

int 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] QString QRegularExpression::wildcardToRegularExpression(const QString &pattern)

Возвращает представление регулярного выражения для заданного шаблона pattern в формате glob. Преобразование ориентировано на сопоставление шаблонов имен файлов, что означает, в частности, что разделители путей обрабатываются особым образом. Это подразумевает, что это не просто базовое преобразование из «*» в «.*».

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

Предупреждение: В отличие от QRegExp, эта реализация тесно следует определению шаблона для паттернов glob:

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

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

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

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

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

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

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

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

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

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

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