Класс QRegularExpression

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

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

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

Типы

Открытые функции

Статические открытые члены

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

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

Класс QRegularExpression обеспечивает сопоставление шаблонов с помощью регулярных выражений.

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

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

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

• Mastering Regular Expressions (Третье издание) Джеффри Э. Ф. Фридла, ISBN 0-596-52812-4;
• страница руководства pcrepattern(3), описывающая синтаксис шаблонов, поддерживаемый PCRE (реализацией-эталоном совместимых с Perl регулярных выражений);
• документация по регулярным выражениям Perl Perl's regular expression documentation и учебное пособие по регулярным выражениям Perl Perl's regular expression tutorial.

Введение

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

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

При использовании QRegExp, классы символов, такие как \w, \d, и т. д., соответствуют символам с соответствующим свойством Юникода: например, \d соответствует любому символу со свойством Юникода 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's --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, QRegularExpression::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, 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 есть имя «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().

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 с текущим регулярным выражением. Эта операция очень быстрая и никогда не приводит к ошибке.

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!=().