Класс 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. Утверждения о поиске назад Perl, «независимые» подвыражения и условные выражения не поддерживаются.

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

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

Примечание: так как C++ преобразует \'s, их необходимо писать дважды в коде, например, \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, может безмолвно изменить семантику. Поэтому необходимо пересмотреть используемые шаблоны. Наиболее заметные случаи скрытой несовместимости:

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

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

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

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

Сопоставление по шаблону

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

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

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

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

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

Режимы «^»

Параметр совпадения 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, если регулярное выражение сопоставляется с учётом регистра; в противном случае возвращает Qt::CaseInsensitive.

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

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

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

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

QString QRegExp::errorString() const

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

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

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

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

Пример:

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

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

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

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

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

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

Для данного регулярного выражения R, exactMatch("R") эквивалентно indexIn("^R$") поскольку exactMatch() фактически заключает регулярное выражение в якоря начала и конца строки, за исключением того, что оно устанавливает 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

Несмотря на const, эта функция устанавливает matchedLength(), capturedTexts() и pos().

Если QRegExp является выражением с подстановкой (см. 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.

Несмотря на const, эта функция устанавливает 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, используется жадное (максимальное) соответствие, которое является по умолчанию.

Например, предположим, что у нас есть входная строка «Мы должны быть <b>жирным</b>, очень <b>жирным</b>!» и шаблон <b>.*</b>. При использовании по умолчанию жадного (максимального) соответствия совпадение равно «Мы должны быть <b>жирным</b>, очень <b>жирным</b>!». Но при минимальном (нежадном) соответствие первое совпадение — «Мы должны быть <b>жирным</b>, очень <b>жирным</b>!», а второе совпадение — «Мы должны быть <b>жирным</b>, очень <b>жирным</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

Возвращает регулярное выражение как QVariant

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

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

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

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

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

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