Класс QRegularExpression

Класс 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("\\\\");

Функция 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::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

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

Перенос частичного сопоставления из 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 нет эквивалента сопоставления с подстановочными знаками. Тем не менее, переписывание регулярного выражения в синтаксисе подстановочных знаков в Perl-совместимое регулярное выражение — очень простая задача, учитывая, что синтаксис подстановочных знаков, поддерживаемый QRegExp, очень прост.

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

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

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

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

Режимы ^

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

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

QRegularExpression внутренне использует компилятор Just-In-Time (JIT), для оптимизации выполнения алгоритма сопоставления. 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()

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

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

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

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

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

QRegularExpression::QRegularExpression(const QRegularExpression &re)

Создаёт объект QRegularExpression как копию re.

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

QRegularExpression::~QRegularExpression()

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

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, MatchType matchType = NormalMatch, MatchOptions matchOptions = NoMatchOption) const

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

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

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

QRegularExpressionMatchIterator QRegularExpression::globalMatch(const QStringRef &subjectRef, int offset = 0, MatchType matchType = NormalMatch, 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, MatchType matchType = NormalMatch, MatchOptions matchOptions = NoMatchOption) const

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

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

См. также QRegularExpressionMatch и обычный поиск.

QRegularExpressionMatch QRegularExpression::match(const QStringRef &subjectRef, int offset = 0, MatchType matchType = NormalMatch, 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-компилятор включен).

Шаблоны обычно оптимизируются только после определённого числа применений. Если можно предсказать, что этот объект QRegularExpression будет использоваться для нескольких поисков, удобно оптимизировать его заранее, вызвав этот метод.

Этот метод был введен в Qt 5.4.

См. также QRegularExpression::OptimizeOnFirstUsageOption.

QString QRegularExpression::pattern() const

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

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

int QRegularExpression::patternErrorOffset() const

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

См. также pattern(), isValid() и errorString().

PatternOptions QRegularExpression::patternOptions() const

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

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

void QRegularExpression::setPattern(const QString &pattern)

Устанавливает строку шаблона регулярного выражения на pattern. Опции шаблона остаются неизменными.

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

void QRegularExpression::setPatternOptions(PatternOptions options)

Устанавливает заданные options в качестве опций шаблона для регулярного выражения. Строка шаблона остаётся неизменной.

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

void QRegularExpression::swap(QRegularExpression &other)

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

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

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

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

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

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

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

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

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

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

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