Класс QRegExp

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

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

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

Типы публичного доступа

Функции публичного доступа

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

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

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

Этот класс устарел в Qt 6. Пожалуйста, используйте QRegularExpression вместо него во всех новых кодах. Для руководства по переносу старого кода с QRegExp на QRegularExpression, см. {Перенос на QRegularExpression}

Регулярное выражение, или «regexp», — это шаблон для поиска подстрок в тексте. Это полезно во многих контекстах, например,

Представлено краткое введение в регулярные выражения, описание языка регулярных выражений Qt, некоторые примеры и сама документация функции. QRegExp моделируется по языку регулярных выражений Perl. Он полностью поддерживает Unicode. QRegExp также может быть использован в более простом режиме подстановок, который аналогичен функциональности, встречающейся в командных оболочках. Правила синтаксиса, используемые QRegExp, можно изменить с помощью setPatternSyntax(). В частности, синтаксис шаблона может быть установлен в QRegExp::FixedString, что означает, что шаблон, который нужно сопоставить, интерпретируется как обычная строка, то есть специальные символы (например, обратный слэш) не экранируются.

Хорошей книгой по регулярным выражениям является Mastering Regular Expressions (Третье издание) Джеффри Е. Ф. Фридла, ISBN 0-596-52812-4.

Примечание: В Qt 5 новый класс QRegularExpression предоставляет совместимую с Perl реализацию регулярных выражений и рекомендуется вместо QRegExp.

Введение

Регулярные выражения строятся из выражений, квантификаторов и утверждений. Самым простым выражением является символ, например x или 5. Выражение также может быть набором символов, заключённых в квадратные скобки. [ABCD] будет соответствовать A или B или C или D. Мы можем записать это же выражение как [A-D], а выражение для соответствия любой заглавной букве английского алфавита записывается как [A-Z].

Квантификатор задаёт количество вхождений выражения, которое должно быть сопоставлено. x{1,1} означает сопоставить ровно одно x. x{1,5} означает сопоставить последовательность символов x, которая содержит по крайней мере один x, но не более пяти.

Обратите внимание, что в общем случае регулярные выражения не могут использоваться для проверки сбалансированных скобок или тегов. Например, регулярное выражение можно написать для соответствия открывающему html <b> и его закрывающему </b>, если <b> теги не вложены, но если <b> теги вложены, то это же регулярное выражение будет соответствовать открывающему <b> тегу с неправильным закрывающим </b>. Для фрагмента <b>bold <b>bolder</b></b>, первый <b> будет сопоставлен с первым </b>, что неверно. Однако, возможно написать регулярное выражение, которое будет правильно сопоставлять вложенные скобки или теги, только если количество уровней вложения фиксировано и известно. Если количество уровней вложения не фиксировано и не известно, невозможно написать регулярное выражение, которое не потерпит неудачу.

Предположим, что нам нужно регулярное выражение для соответствия целым числам в диапазоне от 0 до 99. Требуется по крайней мере одна цифра, поэтому мы начинаем с выражения [0-9]{1,1}, которое соответствует одной цифре ровно один раз. Это регулярное выражение соответствует целым числам от 0 до 9. Чтобы сопоставить целые числа до 99, увеличьте максимальное количество вхождений до 2, таким образом регулярное выражение станет [0-9]{1,2}. Это регулярное выражение удовлетворяет первоначальному требованию соответствия целым числам от 0 до 99, но оно также будет соответствовать целым числам, которые встречаются в середине строк. Если мы хотим, чтобы соответствующее целое число было всей строкой, мы должны использовать утверждения якорей ^ (крышка) и $ (доллар). Когда ^ является первым символом в регулярном выражении, это означает, что регулярное выражение должно соответствовать началу строки. Когда $ является последним символом регулярного выражения, это означает, что регулярное выражение должно соответствовать концу строки. Регулярное выражение становится ^[0-9]{1,2}$. Обратите внимание, что утверждения, например ^ и $, не сопоставляют символы, а позиции в строке.

Если вы видели регулярные выражения, описанные где-то ещё, они могли выглядеть по-другому, чем показано здесь. Это происходит потому, что некоторые наборы символов и некоторые квантификаторы настолько распространены, что им были присвоены специальные символы для их представления. [0-9] можно заменить символом \d. Квантификатор для соответствия ровно одному вхождению {1,1} можно заменить самим выражением, т.е. x{1,1} эквивалентно x. Таким образом, наш сопоставитель от 0 до 99 можно записать как ^\d{1,2}$. Также его можно записать как ^\d\d{0,1}$, т.е. с начала строки, сопоставить цифру, за ней сразу 0 или 1 цифру. На практике это было бы записано как ^\d\d?$. Символ ? является сокращением для квантификатора {0,1}, т.е. 0 или 1 вхождение. ? делает выражение необязательным. Регулярное выражение ^\d\d?$ означает с начала строки, сопоставить одну цифру, за ней сразу 0 или 1 цифру, за ней сразу конец строки.

Чтобы написать регулярное выражение, которое соответствует одному из слов 'mail' или 'letter' или 'correspondence', но не соответствует словам, содержащим эти слова, например 'email', 'mailman', 'mailer', и 'letterbox', начните с регулярного выражения, которое соответствует 'mail'. В полном виде регулярное выражение m{1,1}a{1,1}i{1,1}l{1,1}, но поскольку выражение для символа автоматически квантифицируется {1,1}, мы можем упростить регулярное выражение до mail, т.е. 'm', за которым следует 'a', за которым следует 'i', за которым следует 'l'. Теперь мы можем использовать вертикальную черту |, которая означает или, чтобы включить другие два слова, таким образом наше регулярное выражение для соответствия любому из трёх слов становится mail|letter|correspondence. Сопоставить 'mail' или 'letter' или 'correspondence'. Хотя это регулярное выражение будет сопоставлять одно из трёх слов, которые мы хотим сопоставить, оно также будет сопоставлять слова, которых мы не хотим сопоставлять, например 'email'. Чтобы предотвратить сопоставление регулярным выражением нежелательных слов, мы должны указать ему начать и закончить сопоставление на границах слов. Сначала мы заключаем наше регулярное выражение в скобки (mail|letter|correspondence). Скобки группируют выражения вместе, и они определяют часть регулярного выражения, которую мы хотим захватить. Заключение выражения в скобки позволяет использовать его в качестве компонента в более сложных регулярных выражениях. Это также позволяет нам проверить, какое из трёх слов фактически было сопоставлено. Чтобы принудительно сопоставить начало и конец на границах слов, мы заключаем регулярное выражение в \b границы слов утверждения: \b(mail|letter|correspondence)\b. Теперь регулярное выражение означает: Сопоставить границу слова, за ней регулярное выражение в скобках, за ней границу слова. Утверждение \b сопоставляет позицию в регулярном выражении, а не символ. Граница слова — это любой не-символ слова, например пробел, перевод строки или начало или конец строки.

Если мы хотим заменить символы амперсанда на HTML сущность &, регулярное выражение для соответствия просто &. Но это регулярное выражение также будет сопоставлять амперсанды, которые уже были преобразованы в HTML сущности. Мы хотим заменить только амперсанды, за которыми не следует amp;. Для этого нам нужно отрицательное утверждение о просмотре вперёд, (?!__). Регулярное выражение тогда может быть записано как &(?!amp;), т.е. Сопоставить амперсанд, за которым не следует amp;.

Если мы хотим подсчитать все вхождения 'Eric' и 'Eirik' в строке, два правильных решения — \b(Eric|Eirik)\b и \bEi?ri[ck]\b. Утверждение границы слова '\b' необходимо, чтобы избежать сопоставления слов, содержащих любое из этих имён, например 'Ericsson'. Обратите внимание, что второе регулярное выражение сопоставляет больше вариантов написания, чем мы хотим: 'Eric', 'Erik', 'Eiric' и 'Eirik'.

Некоторые из обсуждаемых выше примеров реализованы в разделе примеров кода.

Символы и сокращения для наборов символов

Примечание: Компилятор C++ преобразует обратные слэши в строках. Чтобы включить \ в регулярное выражение, введите его дважды, т.е. \\. Чтобы сопоставить сам символ обратного слэша, введите его четыре раза, т.е. \\\\.

Наборы символов

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

Использование предопределённых сокращений для набора символов более портативно, чем использование диапазонов символов на разных платформах и языках. Например, [0-9] сопоставляет цифру в западных алфавитах, но \d сопоставляет цифру в любом алфавите.

Примечание: В другой документации по регулярным выражениям наборы символов часто называют «классами символов».

Квантификаторы

По умолчанию, выражение автоматически квантифицируется как {1,1}, т.е. оно должно встречаться ровно один раз. В следующем списке E обозначает выражение. Выражение — это символ, или сокращение для набора символов, или набор символов в квадратных скобках, или выражение в скобках.

Чтобы применить квантификатор к большему, чем просто предыдущий символ, используйте скобки для группировки символов в выражении. Например, tag+ соответствует 't', за которым следует 'a', за которым следует как минимум один 'g', тогда как (tag)+ соответствует как минимум одному вхождению 'tag'.

Примечание: Квантификаторы по умолчанию являются "жадными". Они всегда сопоставляют как можно больше текста. Например, 0+ сопоставляет первую найденную цифру ноль и все последующие нули после первого нуля. При применении к '20005', он сопоставляет '20005'. Квантификаторы могут быть сделаны нежадными, см. setMinimal().

Извлечение текста

Скобки позволяют сгруппировать элементы, чтобы мы могли их квантифицировать и извлекать. Например, если у нас есть выражение mail|letter|correspondence, которое сопоставляет строку, мы знаем, что сопоставлен один из слов, но не какой именно. Использование скобок позволяет "извлечь" всё, что сопоставлено внутри них. Например, если мы использовали (mail|letter|correspondence) и сопоставили это регулярное выражение со строкой "I sent you some email", мы можем использовать функции cap() или capturedTexts() для извлечения сопоставленных символов, в этом случае 'mail'.

Мы можем использовать извлечённый текст внутри самого регулярного выражения. Для ссылки на извлечённый текст мы используем обратные ссылки, индексированные с 1, так же, как и для cap(). Например, мы можем искать дубликаты слов в строке, используя \b(\w+)\W+\1\b, что означает сопоставить границу слова, за которым следует один или несколько символов слова, за которыми следуют один или несколько несимволов слова, за которыми следует тот же текст, что и в первой скобке, за которым следует граница слова.

Если мы хотим использовать скобки только для группировки, а не для извлечения, мы можем использовать синтаксис для невыделения, например, (?:green|blue). Невыделяющие скобки начинаются с '(?:' и заканчиваются ')'. В этом примере мы сопоставляем либо 'green', либо 'blue', но не извлекаем совпадение, поэтому мы только знаем, совпало оно или нет, но не какой цвет мы фактически нашли. Использование невыделяющих скобок более эффективно, чем использование выделяющих скобок, так как двигателю регулярных выражений требуется меньше учета.

Как выделяющие, так и невыделяющие скобки могут быть вложены.

По историческим причинам, квантификаторы (например, *), которые применяются к выделяющим скобкам, являются более "жадными", чем другие квантификаторы. Например, a*(a*) будет сопоставлять "aaa" с cap(1) == "aaa". Это поведение отличается от того, что делают другие движки регулярных выражений (в частности, Perl). Чтобы получить более интуитивное поведение извлечения, укажите QRegExp::RegExp2 конструктору QRegExp или вызовите setPatternSyntax(QRegExp::RegExp2).

Когда количество совпадений заранее неизвестно, распространённым приёмом является использование cap() в цикле. Например:

QRegExp rx("(\\d+)");
QString str = "Offsets: 12 14 99 231 7";
QStringList list;
int pos = 0;

while ((pos = rx.indexIn(str, pos)) != -1) {
    list << rx.cap(1);
    pos += rx.matchedLength();
}
// list: ["12", "14", "99", "231", "7"]

Утверждения

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

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

Большинство командных оболочек, таких как bash или cmd.exe, поддерживают "сопоставление файлов с подстановкой", возможность идентификации группы файлов с помощью подстановочных символов. Функция setPatternSyntax() используется для переключения между режимом регулярных выражений и режимом подстановочных символов. Сопоставление с подстановкой намного проще, чем полные регулярные выражения, и имеет только четыре функции:

В режиме подстановочных символов подстановочные символы не могут быть экранированы. В режиме WildcardUnix символ '\' экранирует подстановочный символ.

Например, если мы находимся в режиме подстановки и имеем строки, содержащие имена файлов, мы могли бы идентифицировать файлы HTML с помощью *.html. Это будет сопоставлять ноль или более символов, за которыми следует точка, за которой следуют 'h', 't', 'm' и 'l'.

Для проверки строки на соответствие выражению с подстановкой используйте exactMatch(). Например:

QRegExp rx("*.txt");
rx.setPatternSyntax(QRegExp::Wildcard);
rx.exactMatch("README.txt");        // returns true
rx.exactMatch("welcome.txt.bak");   // returns false

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

Большинство сокращений для классов символов, поддерживаемых Perl, поддерживаются QRegExp, см. символы и сокращения для наборов символов.

В QRegExp, за исключением внутри наборов символов, ^ всегда обозначает начало строки, поэтому знаки возведения в степень всегда должны быть экранированы, если не используются для этой цели. В Perl смысл знака возведения в степень автоматически изменяется в зависимости от того, где он находится, поэтому экранирование его редко необходимо. То же самое относится к $, который в QRegExp всегда обозначает конец строки.

Квантификаторы QRegExp такие же, как жадные квантификаторы Perl (но см. примечание выше). Нежадное сопоставление не может быть применено к отдельным квантификаторам, но может быть применено ко всем квантификаторам в шаблоне. Например, чтобы сопоставить регулярное выражение Perl ro+?m требуется:

QRegExp rx("ro+m");
rx.setMinimal(true);

Эквивалент параметра Perl /i — setCaseSensitivity(Qt::CaseInsensitive).

Параметр Perl /g можно эмулировать с помощью цикла.

В QRegExp . сопоставляет любой символ, поэтому все регулярные выражения QRegExp имеют эквивалент параметра Perl /s. В QRegExp нет эквивалента параметра Perl /m, но это можно смоделировать различными способами, например, разделив входные данные на строки или используя цикл с регулярным выражением, которое ищет символы новой строки.

Поскольку QRegExp ориентирован на строки, утверждений \A, \Z или \z нет. Утверждение \G не поддерживается, но его можно смоделировать в цикле.

Perl's $& — cap(0) или capturedTexts()[0]. Нет эквивалентов QRegExp для $`, $' или $+. Переменные захвата Perl, $1, $2, ... соответствуют cap(1) или capturedTexts()[1], cap(2) или capturedTexts()[2] и т.д.

Для подстановки шаблона используйте QString::replace().

Расширенный синтаксис /x Perl не поддерживается, также не поддерживаются директивы, например (?i), или комментарии к регулярному выражению, например (?#comment). С другой стороны, правила C++ для строковых литералов можно использовать для достижения того же.

QRegExp mark("\\b"      // word boundary
              "[Mm]ark" // the word we want to match
            );

Поддерживаются утверждения с нулевой шириной — положительные (?=pattern) и отрицательные (?!pattern) — с тем же синтаксисом, что и в Perl. Утверждения lookbehind Perl, «независимые» подвыражения и условные выражения не поддерживаются.

Также поддерживаются незахватывающие скобки с тем же синтаксисом (?:pattern).

См. QString::split() и QStringList::join() для эквивалентов функций split и join Perl.

Примечание: поскольку C++ преобразует обратные слэши, они должны быть написаны дважды в коде, например, \b необходимо написать \\b.

Примеры кода

QRegExp rx("^\\d\\d?$");    // match integers 0 to 99
rx.indexIn("123");          // returns -1 (no match)
rx.indexIn("-6");           // returns -1 (no match)
rx.indexIn("6");            // returns 0 (matched at position 0)

Третья строка соответствует '6'. Это простой валидирующий регулярный выражение для целых чисел в диапазоне от 0 до 99.

QRegExp rx("^\\S+$");       // match strings without whitespace
rx.indexIn("Hello world");  // returns -1 (no match)
rx.indexIn("This_is-OK");   // returns 0 (matched at position 0)

Вторая строка соответствует 'This_is-OK'. Мы использовали сокращение символьного класса '\S' (непробельный символ) и якоря для соответствия строкам, не содержащим пробелы.

В следующем примере мы ищем строки, содержащие 'mail' или 'letter' или 'correspondence', но только целые слова, т. е. не 'email'

QRegExp rx("\\b(mail|letter|correspondence)\\b");
rx.indexIn("I sent you an email");     // returns -1 (no match)
rx.indexIn("Please write the letter"); // returns 17

Вторая строка соответствует «Please write the letter». Слово «letter» также захватывается (из-за скобок). Мы можем увидеть, какой текст мы захватили следующим образом:

QString captured = rx.cap(1); // captured == "letter"

Это позволит захватить текст из первой пары захватывающих скобок (считая захватывающие левые скобки слева направо). Скобки нумеруются с 1, так как cap(0) — это всё совпавшее регулярное выражение (эквивалент '&' в большинстве движков регулярных выражений).

QRegExp rx("&(?!amp;)");      // match ampersands but not &
QString line1 = "This & that";
line1.replace(rx, "&");
// line1 == "This & that"
QString line2 = "His & hers & theirs";
line2.replace(rx, "&");
// line2 == "His & hers & theirs"

Здесь мы передали QRegExp в функцию replace() QString для замены совпавшего текста новым текстом.

QString str = "One Eric another Eirik, and an Ericsson. "
              "How many Eiriks, Eric?";
QRegExp rx("\\b(Eric|Eirik)\\b"); // match Eric or Eirik
int pos = 0;    // where we are in the string
int count = 0;  // how many Eric and Eirik's we've counted
while (pos >= 0) {
    pos = rx.indexIn(str, pos);
    if (pos >= 0) {
        ++pos;      // move along in str
        ++count;    // count our Eric or Eirik
    }
}

Мы использовали функцию indexIn() для многократного поиска регулярного выражения в строке. Обратите внимание, что вместо посимвольного продвижения pos++ мы могли бы написать pos += rx.matchedLength() для пропуска уже найденной строки. Количество совпадений будет равно 3, соответствие — 'One Eric another Eirik, and an Ericsson. How many Eiriks, Eric?'; оно не соответствует 'Ericsson' или 'Eiriks', потому что они не ограничены границами слов.

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

str = "The Qt Company Ltd\tqt.io\tFinland";
QString company, web, country;
rx.setPattern("^([^\t]+)\t([^\t]+)\t([^\t]+)$");
if (rx.indexIn(str) != -1) {
    company = rx.cap(1);
    web = rx.cap(2);
    country = rx.cap(3);
}

В этом примере наши строки ввода имеют формат название компании, веб-адрес и страна. К сожалению, регулярное выражение довольно длинное и не очень универсальное — код сломается, если мы добавим еще больше полей. Более простое и лучшее решение — искать разделитель, в данном случае '\t', и брать окружающий текст. Функция QString::split() может принимать в качестве аргумента строку-разделитель или регулярное выражение и разделять строку соответственно.

QStringList field = str.split("\t");

Здесь field[0] — это компания, field[1] — веб-адрес и т. д.

Для имитации соответствия оболочки можно использовать режим подстановок.

QRegExp rx("*.html");
rx.setPatternSyntax(QRegExp::Wildcard);
rx.exactMatch("index.html");                // returns true
rx.exactMatch("default.htm");               // returns false
rx.exactMatch("readme.txt");                // returns false

Сопоставление с подстановками может быть удобным из-за простоты, но любое регулярное выражение с подстановкой можно определить с помощью полных регулярных выражений, например, .*\.html$. Обратите внимание, что мы не можем сопоставить оба .html и .htm файла с подстановкой, если не использовать *.htm*, что также будет соответствовать 'test.html.bak'. Полное регулярное выражение обеспечивает необходимую точность, .*\.html?$.

QRegExp может выполнять поиск без учета регистра с помощью setCaseSensitivity() и может использовать нежадный поиск, см. setMinimal(). По умолчанию QRegExp использует полные регулярные выражения, но это можно изменить с помощью setPatternSyntax(). Поиск может выполняться вперед с помощью indexIn() или назад с помощью lastIndexIn(). К захваченному тексту можно получить доступ с помощью capturedTexts(), которая возвращает список строк всех захваченных строк, или с помощью cap(), которая возвращает захваченную строку для данного индекса. Функция pos() принимает индекс совпадения и возвращает позицию в строке, где произошло совпадение (или -1, если совпадения не было).

Миграция на QRegularExpression

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

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

Различия в синтаксисе шаблонов

Миграция регулярного выражения из QRegExp в QRegularExpression может потребовать изменений в самом шаблоне.

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

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

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

Миграция из QRegExp::exactMatch()

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

Миграция точного соответствия из QRegExp

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

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

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

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

Миграция частичного соответствия из QRegExp

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

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

Глобальный поиск

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

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

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

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

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

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

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

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

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

Нежадный поиск

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

Режимы символа ^

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

См. также QString, QStringList и QSortFilterProxyModel.

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

enum QRegExp::CaretMode

Перечисление CaretMode определяет различные значения символа возврат каретки (^) в регулярном выражении. Возможные значения:

enum QRegExp::PatternSyntax

Синтаксис, используемый для интерпретации смысла шаблона.

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

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

QRegExp::QRegExp(const QRegExp &rx)

Конструирует регулярное выражение как копию rx.

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

QRegExp::QRegExp(const QString &pattern, Qt::CaseSensitivity cs = Qt::CaseSensitive, QRegExp::PatternSyntax syntax = RegExp)

Конструирует объект регулярного выражения для заданной строки pattern. Шаблон должен быть задан с использованием нотации подстановок, если syntax — Wildcard; по умолчанию — RegExp. Шаблон чувствителен к регистру, если cs не Qt::CaseInsensitive. Сопоставление жадное (максимальное), но может быть изменено вызовом setMinimal().

См. также setPattern(), setCaseSensitivity() и setPatternSyntax().

QRegExp::QRegExp()

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

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

[since 5.2] QRegExp &QRegExp::operator=(QRegExp &&other)

Перемещает other в экземпляр QRegExp.

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

QRegExp &QRegExp::operator=(const QRegExp &rx)

Копирует регулярное выражение rx и возвращает ссылку на копию. Также копируются параметры чувствительности к регистру, нотации подстановок и минимального соответствия.

QRegExp::~QRegExp()

Уничтожает регулярное выражение и очищает свои внутренние данные.

QString QRegExp::cap(int nth = 0) const

Возвращает текст, захваченный nth подвыражением. Весь совпавший фрагмент имеет индекс 0, а скобочные подвыражения — индексы, начинающиеся с 1 (исключая незахватывающие скобки).

QRegExp rxlen("(\\d+)(?:\\s*)(cm|inch)");
int pos = rxlen.indexIn("Length: 189cm");
if (pos > -1) {
    QString value = rxlen.cap(1); // "189"
    QString unit = rxlen.cap(2);  // "cm"
    // ...
}

Порядок элементов, сопоставленных с помощью cap(), следующий. Первый элемент cap(0) — это вся совпавшая строка. Каждый последующий элемент соответствует следующей открывающей захватывающей левой скобке. Таким образом, cap(1) — это текст первой захватывающей скобки, cap(2) — второй и так далее.

См. также capturedTexts() и pos().

int QRegExp::captureCount() const

Возвращает количество захватов, содержащихся в регулярном выражении.

QStringList QRegExp::capturedTexts() const

Возвращает список захваченных строк.

Первая строка в списке — это вся совпавшая строка. Каждый последующий элемент списка содержит строку, соответствующую захватывающему подвыражению регулярного выражения.

Например:

QRegExp rx("(\\d+)(\\s*)(cm|inch(es)?)");
int pos = rx.indexIn("Length: 36 inches");
QStringList list = rx.capturedTexts();
// list is now ("36 inches", "36", " ", "inches", "es")

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

QRegExp rx("(\\d+)(?:\\s*)(cm|inch(?:es)?)");
int pos = rx.indexIn("Length: 36 inches");
QStringList list = rx.capturedTexts();
// list is now ("36 inches", "36", "inches")

Обратите внимание, что при итерации по списку необходимо итерироваться по его копии, например:

QStringList list = rx.capturedTexts();
QStringList::iterator it = list.begin();
while (it != list.end()) {
    myProcessing(*it);
    ++it;
}

Некоторые регулярные выражения могут совпадать неопределенное количество раз. Например, если входная строка — «Offsets: 12 14 99 231 7», а регулярное выражение — (\d+)+, то мы надеемся получить список всех сопоставленных чисел. Однако после вызова rx.indexIn(str), capturedTexts() вернет список («12», «12»), то есть весь совпавший фрагмент — «12», а первое подвыражение совпало с «12». Правильный подход — использовать cap() в цикле.

Порядок элементов в списке строк следующий. Первый элемент — это вся совпавшая строка. Каждый последующий элемент соответствует следующей открывающей захватывающей левой скобке. Таким образом, capturedTexts()[1] — это текст первой захватывающей скобки, capturedTexts()[2] — второй и так далее (соответствуя $1, $2 и т. д. в некоторых других языках регулярных выражений).

См. также cap() и pos().

Qt::CaseSensitivity QRegExp::caseSensitivity() const

Возвращает Qt::CaseSensitive, если regexp чувствителен к регистру; в противном случае возвращает Qt::CaseInsensitive.

См. также setCaseSensitivity(), patternSyntax(), pattern() и isMinimal().

int QRegExp::countIn(const QString &str) const

Возвращает количество совпадений данного регулярного выражения в str.

См. также indexIn(), lastIndexIn() и replaceIn().

QString QRegExp::errorString() const

Возвращает строку, объясняющую, почему шаблон regexp недействителен, в противном случае возвращает «ошибка не произошла».

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

[static] QString QRegExp::escape(const QString &str)

Возвращает строку str, в которой каждый специальный символ regexp экранирован обратной косой чертой. Специальные символы: $, (,), *, +, ., ?, [, ], ^, {, | и }.

Пример:

s1 = QRegExp::escape("bingo");   // s1 == "bingo"
s2 = QRegExp::escape("f(x)");    // s2 == "f\\(x\\)"

Эта функция полезна для динамического создания шаблонов regexp:

QRegExp rx("(" + QRegExp::escape(name) +
           "|" + QRegExp::escape(alias) + ")");

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

bool QRegExp::exactMatch(const QString &str) const

Возвращает true, если str точно соответствует данному регулярному выражению; в противном случае возвращает false. Вы можете определить, какая часть строки была сопоставлена, вызвав matchedLength().

Для заданной строки regexp R, exactMatch("R") эквивалентно indexIn("^R$") так как exactMatch() фактически включает regexp в якорные символы начала и конца строки, за исключением того, что он задает matchedLength() по-другому.

Например, если регулярное выражение — blue, то exactMatch() возвращает true только для входа blue. Для входов bluebell, blutak и lightblue, exactMatch() возвращает false, а matchedLength() вернет 4, 3 и 0 соответственно.

Хотя функция является константной, она устанавливает matchedLength(), capturedTexts() и pos().

См. также indexIn() и lastIndexIn().

QStringList QRegExp::filterList(const QStringList &stringList) const

Возвращает список всех строк, которые соответствуют данному регулярному выражению в stringList.

int QRegExp::indexIn(const QString &str, int offset = 0, QRegExp::CaretMode caretMode = CaretAtZero) const

Попытка найти совпадение в str с позиции offset (по умолчанию 0). Если offset равно -1, поиск начинается с последнего символа; если -2, со второго с конца и т.д.

Возвращает позицию первого совпадения или -1, если совпадений нет.

Параметр caretMode используется для указания, должно ли ^ соответствовать индексу 0 или offset.

Возможно, вам будет удобнее использовать QString::indexOf(), QString::contains() или даже QStringList::filter(). Для замены совпадений используйте QString::replace().

Пример:

QString str = "offsets: 1.23 .50 71.00 6.00";
QRegExp rx("\\d*\\.\\d+");    // primitive floating point matching
int count = 0;
int pos = 0;
while ((pos = rx.indexIn(str, pos)) != -1) {
    ++count;
    pos += rx.matchedLength();
}
// pos will be 9, 14, 18 and finally 24; count will end up as 4

Хотя функция является константной, она устанавливает matchedLength(), capturedTexts() и pos().

Если регулярное выражение является выражением с подстановкой (см. setPatternSyntax()), и нужно проверить строку на соответствие всему выражению с подстановкой, используйте exactMatch() вместо этой функции.

См. также lastIndexIn() и exactMatch().

int QRegExp::indexIn(const QStringList &list, int from) const

Возвращает индекс первого точного совпадения этого регулярного выражения в list, начиная поиск с индекса from. Возвращает -1, если совпадений нет.

См. также lastIndexIn() и exactMatch().

bool QRegExp::isEmpty() const

Возвращает true если строка шаблона пустая; в противном случае возвращает false.

Если вызвать exactMatch() с пустым шаблоном на пустой строке, она вернёт true; в противном случае вернёт false, так как работает с целой строкой. Если вызвать indexIn() с пустым шаблоном на любой строке, она вернёт начальный смещение (0 по умолчанию), потому что пустой шаблон соответствует пустоте в начале строки. В этом случае длина совпадения, возвращаемая matchedLength(), будет 0.

См. QString::isEmpty().

bool QRegExp::isMinimal() const

Возвращает true если включено минимальное (нежадное) соответствие; в противном случае возвращает false.

См. также caseSensitivity() и setMinimal().

bool QRegExp::isValid() const

Возвращает true если регулярное выражение валидно; в противном случае возвращает false. Невалидное регулярное выражение никогда не соответствует шаблону.

Шаблон [a-z является примером невалидного шаблона, так как ему не хватает закрывающей квадратной скобки.

Обратите внимание, что валидность регулярного выражения может также зависеть от флага подстановки, например, *.html — валидное регулярное выражение с подстановкой, но невалидное полное регулярное выражение.

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

int QRegExp::lastIndexIn(const QString &str, int offset = -1, QRegExp::CaretMode caretMode = CaretAtZero) const

Попытка найти совпадение в обратном порядке в str с позиции offset. Если offset равно -1 (по умолчанию), поиск начинается с последнего символа; если -2, со второго с конца и т.д.

Возвращает позицию первого совпадения или -1, если совпадений нет.

Параметр caretMode используется для указания, должно ли ^ соответствовать индексу 0 или offset.

Хотя функция является константной, она устанавливает matchedLength(), capturedTexts() и pos().

Предупреждение: Поиск в обратном направлении значительно медленнее, чем поиск в прямом направлении.

См. также indexIn() и exactMatch().

int QRegExp::lastIndexIn(const QStringList &list, int from) const

Возвращает индекс последнего точного совпадения этого регулярного выражения в list, начиная поиск с индекса from в обратном порядке. Если from равно -1 (по умолчанию), поиск начинается с последнего элемента. Возвращает -1, если совпадений нет.

См. также QRegExp::exactMatch().

int QRegExp::matchedLength() const

Возвращает длину последней сопоставленной строки или -1, если совпадений нет.

См. также exactMatch(), indexIn() и lastIndexIn().

QString QRegExp::pattern() const

Возвращает строку шаблона регулярного выражения. Шаблон использует синтаксис регулярных выражений или синтаксис подстановок в зависимости от patternSyntax().

См. также setPattern(), patternSyntax() и caseSensitivity().

QRegExp::PatternSyntax QRegExp::patternSyntax() const

Возвращает синтаксис, используемый регулярным выражением. По умолчанию используется QRegExp::RegExp.

См. также setPatternSyntax(), pattern() и caseSensitivity().

int QRegExp::pos(int nth = 0) const

Возвращает позицию nth захваченного текста в строке поиска. Если nth равно 0 (по умолчанию), pos() возвращает позицию всего совпадения.

Пример:

QRegExp rx("/([a-z]+)/([a-z]+)");
rx.indexIn("Output /dev/null");   // returns 7 (position of /dev/null)
rx.pos(0);                        // returns 7 (position of /dev/null)
rx.pos(1);                        // returns 8 (position of dev)
rx.pos(2);                        // returns 12 (position of null)

Для совпадений нулевой длины pos() всегда возвращает -1. (Например, если cap(4) возвращает пустую строку, pos(4) возвращает -1.) Это особенность реализации.

См. также cap() и capturedTexts().

QString QRegExp::removeIn(const QString &str) const

Удаляет все вхождения этого регулярного выражения в str и возвращает результат.

Делает то же самое, что и replaceIn(str, QString()).

См. также indexIn(), lastIndexIn() и replaceIn().

QString QRegExp::replaceIn(const QString &str, const QString &after) const

Заменяет все вхождения этого регулярного выражения в str на after и возвращает результат.

Для регулярных выражений, содержащих захватывающие скобки, вхождения \1, \2, ..., в after заменяются на rx.cap(1), cap(2), ...

См. также indexIn(), lastIndexIn() и QRegExp::cap().

QStringList QRegExp::replaceIn(const QStringList &stringList, const QString &after) const

Заменяет все вхождения этого регулярного выражения в каждой строке stringList на after. Возвращает список строк.

void QRegExp::setCaseSensitivity(Qt::CaseSensitivity cs)

Устанавливает чувствительность к регистру на cs.

Если cs равно Qt::CaseSensitive, \.txt$ соответствует readme.txt, но не README.TXT.

См. также caseSensitivity(), setPatternSyntax(), setPattern() и setMinimal().

void QRegExp::setMinimal(bool minimal)

Включает или отключает минимальное соответствие. Если minimal равно false, соответствие жадное (максимальное), что является значением по умолчанию.

Например, предположим, что у нас есть входная строка "We must be <b>bold</b>, very <b>bold</b>!" и шаблон <b>.*</b>. При стандартном жадном (максимальном) соответствии совпадение — "We must be <b>bold</b>, very <b>bold</b>!". Но при минимальном (нежадном) соответствии первое совпадение — "We must be <b>bold</b>, very <b>bold</b>!", а второе совпадение — "We must be <b>bold</b>, very <b>bold</b>!". На практике мы могли бы использовать шаблон <b>[^<]*</b> вместо этого, хотя он всё равно не справится с вложенными тегами.

См. также isMinimal() и setCaseSensitivity().

void QRegExp::setPattern(const QString &pattern)

Устанавливает строку шаблона на pattern. Чувствительность к регистру, параметры подстановочных знаков и минимального соответствия не изменяются.

См. также pattern(), setPatternSyntax() и setCaseSensitivity().

void QRegExp::setPatternSyntax(QRegExp::PatternSyntax syntax)

Устанавливает режим синтаксиса для регулярного выражения. По умолчанию используется QRegExp::RegExp.

Установление syntax в QRegExp::Wildcard включает простые режимы подстановки, подобные командной строке. Сопоставление с шаблонами QRegExp в режиме подстановочных знаков. Например, r*.txt сопоставляется со строкой readme.txt, но не со строкой readme.

Установка syntax в QRegExp::FixedString означает, что шаблон интерпретируется как обычная строка. Специальные символы (например, обратная косая черта) при этом не требуют экранирования.

См. также patternSyntax(), setPattern(), setCaseSensitivity() и escape().

QStringList QRegExp::splitString(const QString &str, Qt::SplitBehavior behavior = Qt::KeepEmptyParts) const

Разбивает str на подстроки в местах совпадения с этим регулярным выражением и возвращает список этих строк. Если это регулярное выражение не совпадает нигде в строке, split() возвращает список, содержащий только одну строку str.

Если behavior установлено в Qt::KeepEmptyParts, пустые поля включаются в результирующий список.

См. также QStringList::join() и QString::split().

void QRegExp::swap(QRegExp &other)

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

QVariant QRegExp::operator QVariant() const

Возвращает regexp как QVariant

bool QRegExp::operator!=(const QRegExp &rx) const

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

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

bool QRegExp::operator==(const QRegExp &rx) const

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

Два объекта QRegExp равны, если у них одинаковые строки шаблонов и одинаковые настройки чувствительности к регистру, подстановочных знаков и минимального соответствия.