Класс QRegularExpression

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

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

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

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

Публичные типы

Публичные функции

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

Связанные нечлены

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

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

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

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

• Mastering Regular Expressions (Третье издание) Джеффри Е. Ф. Фридла, 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() для существующего объекта 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() для получения следующего результата без перемещения итератора.

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

В определённых сценариях QRegExp был слишком снисходительным и принимал шаблоны, которые просто недействительны при использовании QRegularExpression. Их довольно легко обнаружить, поскольку объекты QRegularExpression, созданные с этими шаблонами, недействительны (см. isValid()).

В других случаях шаблон, перенесённый из QRegExp в QRegularExpression, может тихо изменить семантику. Поэтому необходимо пересмотреть используемые шаблоны. Наиболее заметными случаями тихой несовместимости являются:

• Фигурные скобки необходимы для использования шестнадцатеричного экранирования, такого как \xHHHH с более чем 2 цифрами. Шаблон, подобный \x2022, необходимо перенести в \x{2022}, иначе он будет сопоставлять пробел (0x20) и строку "22". В общем случае настоятельно рекомендуется всегда использовать фигурные скобки с экранированием \x независимо от количества указанных цифр.
• Квантификация от 0 до n, например {,n}, должна быть перенесена в {0,n}, чтобы сохранить семантику. В противном случае шаблон, такой как \d{,3}, на самом деле будет сопоставлять цифру и точную строку "{,3}".
• QRegExp по умолчанию выполняет сопоставление с учётом Unicode, в то время как QRegularExpression требует отдельного параметра; см. подробности ниже.

Перевод из QRegExp::exactMatch()

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

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

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

Точное сопоставление не отражается в QRegularExpression. Если вы хотите убедиться, что строка-предмет точно соответствует регулярному выражению, вы можете обернуть шаблон с помощью функции anchoredPattern():

QString p("a .*|pattern");

// re matches exactly the pattern string p
QRegularExpression re(QRegularExpression::anchoredPattern(p));

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

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

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

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

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

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

Поддержка свойств Unicode

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

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

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

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

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

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

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

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

Режимы «caret»

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

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

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

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

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

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

enum QRegularExpression::MatchOptionflags QRegularExpression::MatchOptions

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

enum QRegularExpression::MatchType

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

enum QRegularExpression::PatternOptionflags 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);

Примечание: Эта функция реализует алгоритм quotemeta Perl и экранирует обратной косой чертой все символы в 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 внутри объекта subject, используя тип сопоставления 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 есть имя «day», у захватывающей группы #2 есть имя «month» и так далее.

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

Данная функция была добавлена в 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

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

Предупреждение: В отличие от 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!=().