QRegularExpression Class

Descripción detallada

Las expresiones regulares, o regexps, son una herramienta muy potente para manejar cadenas y textos. Esto es útil en muchos contextos, p. ej,

Este documento no es en absoluto una referencia completa a la concordancia de patrones mediante expresiones regulares, y las siguientes partes requerirán que el lector tenga algunos conocimientos básicos sobre las expresiones regulares tipo Perl y su sintaxis de patrones.

Buenas referencias sobre expresiones regulares incluyen:

• Mastering Regular Expressions (Third Edition) por Jeffrey E. F. Friedl, ISBN 0-596-52812-4;
• la página man pcrepattern(3), que describe la sintaxis de patrones soportada por PCRE (la implementación de referencia de expresiones regulares compatibles con Perl);
• la documentación sobre expresiones regulares de Perl y el tutorial sobre expresiones regulares de Perl.

Introducción

QRegularExpression implementa expresiones regulares compatibles con Perl. Es totalmente compatible con Unicode. Para una visión general de la sintaxis de las expresiones regulares soportadas por QRegularExpression, por favor consulte la página man pcrepattern(3) antes mencionada. Una expresión regular se compone de dos cosas: una cadena patrón y un conjunto de opciones de patrón que cambian el significado de la cadena patrón.

Puede establecer la cadena patrón pasando una cadena al constructor de QRegularExpression:

QRegularExpression re("a pattern");

Esto establece la cadena de patrón a a pattern. También puede utilizar la función setPattern() para establecer un patrón en un objeto QRegularExpression existente:

QRegularExpression re;
re.setPattern("another pattern");

Tenga en cuenta que debido a las reglas de cadenas literales de C++, debe escapar todas las barras invertidas dentro de la cadena de patrón con otra barra invertida:

// matches two digits followed by a space and a word
QRegularExpression re("\\d\\d \\w+");

// matches a backslash
QRegularExpression re2("\\\\");

Alternativamente, puede utilizar una cadena literal sin procesar, en cuyo caso no necesita escapar las barras invertidas en el patrón, todos los caracteres entre R"(...)" se consideran caracteres sin procesar. Como puede ver en el siguiente ejemplo, esto simplifica la escritura de patrones:

// matches two digits followed by a space and a word
QRegularExpression re(R"(\d\d \w+)");

La función pattern() devuelve el patrón actualmente establecido para un objeto QRegularExpression:

QRegularExpression re("a third pattern");
QString pattern = re.pattern(); // pattern == "a third pattern"

Opciones de patrón

El significado de la cadena del patrón puede modificarse estableciendo una o más opciones de patrón. Por ejemplo, es posible configurar un patrón para que no distinga entre mayúsculas y minúsculas configurando QRegularExpression::CaseInsensitiveOption.

Puede establecer las opciones pasándolas al constructor de QRegularExpression, como en:

// matches "Qt rocks", but also "QT rocks", "QT ROCKS", "qT rOcKs", etc.
QRegularExpression re("Qt rocks", QRegularExpression::CaseInsensitiveOption);

Alternativamente, puede utilizar la función setPatternOptions() en un QRegularExpressionObject existente:

QRegularExpression re("^\\d+$");
re.setPatternOptions(QRegularExpression::MultilineOption);
// re matches any line in the subject string that contains only digits (but at least one)

Es posible obtener las opciones de patrón actualmente establecidas en un objeto QRegularExpression utilizando la función patternOptions():

QRegularExpression re = QRegularExpression("^two.*words$", QRegularExpression::MultilineOption
                                                        | QRegularExpression::DotMatchesEverythingOption);

QRegularExpression::PatternOptions options = re.patternOptions();
// options == QRegularExpression::MultilineOption | QRegularExpression::DotMatchesEverythingOption

Consulte la documentación del enum QRegularExpression::PatternOption para obtener más información sobre cada opción de patrón.

Tipo de coincidencia y opciones de coincidencia

Los dos últimos argumentos de las funciones match() y globalMatch() establecen el tipo de coincidencia y las opciones de coincidencia. El tipo de coincidencia es un valor del enum QRegularExpression::MatchType; el algoritmo de coincidencia "tradicional" se elige utilizando el tipo de coincidencia NormalMatch (por defecto). También es posible activar la coincidencia parcial de la expresión regular con una cadena de asunto: consulte la sección partial matching para obtener más detalles.

Las opciones de coincidencia son un conjunto de uno o más valores de QRegularExpression::MatchOption. Modifican el modo en que se realiza una coincidencia específica de una expresión regular con una cadena de asunto. Consulte la documentación de QRegularExpression::MatchOption para obtener más detalles.

Coincidencia normal

Para realizar una coincidencia puede simplemente invocar la función match() pasando una cadena con la que realizar la coincidencia. Esta cadena se denomina cadena de asunto. El resultado de la función match() es un objeto QRegularExpressionMatch que puede utilizarse para inspeccionar los resultados de la comparación. Por ejemplo:

// 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

Si una coincidencia tiene éxito, el grupo de captura (implícito) número 0 puede utilizarse para recuperar la subcadena coincidente con el patrón completo (véase también la sección sobre extracting captured substrings):

QRegularExpression re("\\d\\d \\w+");
QRegularExpressionMatch match = re.match("abc123 def");
if (match.hasMatch()) {
    QString matched = match.captured(0); // matched == "23 def"
    // ...
}

También es posible iniciar una coincidencia en un desplazamiento arbitrario dentro de la cadena de asunto pasando el desplazamiento como argumento de la función match(). En el siguiente ejemplo "12 abc" no coincide porque la coincidencia se inicia en el desplazamiento 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"
    // ...
}

Extracción de las subcadenas capturadas

El objeto QRegularExpressionMatch contiene también información sobre las subcadenas capturadas por los grupos de captura en la cadena patrón. La función captured() devolverá la cadena capturada por el n-ésimo grupo de captura:

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"
    // ...
}

Los grupos de captura del patrón se numeran empezando por 1, y el grupo de captura implícito 0 se utiliza para capturar la subcadena que coincide con todo el patrón.

También es posible recuperar los desplazamientos inicial y final (dentro de la cadena de asunto) de cada subcadena capturada, utilizando las funciones capturedStart() y 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
    // ...
}

Todas estas funciones tienen una sobrecarga que toma un QString como parámetro para extraer las subcadenas capturadas con nombre. Por ejemplo:

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
}

Coincidencia global

Laconcordancia global es útil para encontrar todas las apariciones de una expresión regular dada dentro de una cadena de asunto. Supongamos que queremos extraer todas las palabras de una cadena dada, donde una palabra es una subcadena que coincide con el patrón \w+.

QRegularExpression::globalMatch devuelve un QRegularExpressionMatchIterator, que es un iterador hacia adelante de tipo Java que puede utilizarse para iterar sobre los resultados. Por ejemplo:

QRegularExpression re("(\\w+)");
QRegularExpressionMatchIterator i = re.globalMatch("the quick fox");

Como es un iterador tipo Java, el QRegularExpressionMatchIterator apuntará inmediatamente antes del primer resultado. Cada resultado se devuelve como un objeto QRegularExpressionMatch. La función hasNext() devolverá true si hay al menos un resultado más, y next() devolverá el siguiente resultado y hará avanzar el iterador. Continuando con el ejemplo anterior:

QStringList words;
while (i.hasNext()) {
    QRegularExpressionMatch match = i.next();
    QString word = match.captured(1);
    words << word;
}
// words contains "the", "quick", "fox"

También puede utilizar peekNext() para obtener el siguiente resultado sin hacer avanzar el iterador.

También es posible utilizar simplemente el resultado de QRegularExpression::globalMatch en un bucle for basado en rangos, por ejemplo así:

// using a raw string literal, R"(raw_characters)", to be able to use "\w"
// without having to escape the backslash as "\\w"
QRegularExpression re(R"(\w+)");
QString subject("the quick fox");
for (const QRegularExpressionMatch &match : re.globalMatch(subject)) {
    // ...
}

Es posible pasar un desplazamiento inicial y una o más opciones de coincidencia a la función globalMatch(), exactamente igual que la coincidencia normal con match().

Comparación parcial

Se obtiene una coincidencia parcial cuando se alcanza el final de la cadena de asunto, pero se necesitan más caracteres para completar con éxito la coincidencia. Tenga en cuenta que una coincidencia parcial suele ser mucho más ineficiente que una coincidencia normal porque no se pueden emplear muchas optimizaciones del algoritmo de coincidencia.

Una coincidencia parcial debe solicitarse explícitamente especificando un tipo de coincidencia de PartialPreferCompleteMatch o PartialPreferFirstMatch al llamar a QRegularExpression::match o QRegularExpression::globalMatch. Si se encuentra una coincidencia parcial, al llamar a la función hasMatch() sobre el objeto QRegularExpressionMatch devuelto por match() se obtendrá false, pero hasPartialMatch() devolverá true.

Cuando se encuentra una coincidencia parcial, no se devuelve ninguna subcadena capturada, y el grupo de captura (implícito) 0 correspondiente a la coincidencia completa captura la subcadena parcialmente coincidente de la cadena de asunto.

Tenga en cuenta que pedir una coincidencia parcial aún puede conducir a una coincidencia completa, si se encuentra alguna; en este caso, hasMatch() devolverá true y hasPartialMatch() false. Nunca ocurre que un QRegularExpressionMatch informe tanto de una coincidencia parcial como de una completa.

Las coincidencias parciales son útiles principalmente en dos situaciones: la validación de la entrada del usuario en tiempo real y las coincidencias incrementales/multisegmento.

Validación de la entrada del usuario

Supongamos que queremos que el usuario introduzca una fecha en un formato específico, por ejemplo "MMM dd, aaaa". Podemos comprobar la validez de la entrada con un patrón como:

^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d\d?, \d\d\d\d$

(Este patrón no detecta los días no válidos, pero vamos a mantenerlo para los propósitos del ejemplo).

Nos gustaría validar la entrada con esta expresión regular mientras el usuario la teclea, de forma que podamos informar de un error en la entrada tan pronto como se cometa (por ejemplo, el usuario tecleó la tecla equivocada). Para ello debemos distinguir tres casos:

• la entrada no puede coincidir con la expresión regular;
• la entrada coincide con la expresión regular;
• la entrada no coincide con la expresión regular en este momento, pero lo hará si se le añaden más caracteres.

Tenga en cuenta que estos tres casos representan exactamente los posibles estados de QValidator (véase el enum QValidator::State ).

En particular, en el último caso queremos que el motor de expresión regular informe de una coincidencia parcial: estamos comparando con éxito el patrón con la cadena de asunto, pero la coincidencia no puede continuar porque se ha encontrado el final del asunto. Tenga en cuenta, sin embargo, que el algoritmo de coincidencia debe continuar y probar todas las posibilidades, y en caso de que se encuentre una coincidencia completa (no parcial), entonces ésta debe ser reportada, y la cadena de entrada aceptada como totalmente válida.

Este comportamiento se implementa mediante el tipo de coincidencia PartialPreferCompleteMatch. Por ejemplo:

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

Si al cotejar la misma expresión regular con la cadena de asunto se obtiene una coincidencia completa, se informa de ello como de costumbre:

QString input("Dec 8, 1985");
QRegularExpressionMatch match = re.match(input, 0, QRegularExpression::PartialPreferCompleteMatch);
bool hasMatch = match.hasMatch(); // true
bool hasPartialMatch = match.hasPartialMatch(); // false

Otro ejemplo con un patrón diferente, que muestra el comportamiento de preferir una coincidencia completa a una parcial:

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"

En este caso, el sub-patrón abc\\w+X coincide parcialmente con la cadena de asunto; sin embargo, el sub-patrón def coincide completamente con la cadena de asunto, y por lo tanto se informa de una coincidencia completa.

Si se encuentran varias coincidencias parciales al realizar la búsqueda (pero ninguna coincidencia completa), el objeto QRegularExpressionMatch informará de la primera que se encuentre. Por ejemplo:

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"

Coincidencia incremental/multisegmento

La concordancia incremental es otro caso de uso de la concordancia parcial. Supongamos que queremos encontrar las ocurrencias de una expresión regular dentro de un texto grande (es decir, las subcadenas que coinciden con la expresión regular). Para ello, nos gustaría "alimentar" los motores de expresiones regulares con el texto en trozos más pequeños. El problema obvio es qué ocurre si la subcadena que coincide con la expresión regular abarca dos o más trozos.

En este caso, el motor de expresión regular debería informar de una coincidencia parcial, para que podamos volver a coincidir añadiendo nuevos datos y (finalmente) obtener una coincidencia completa. Esto implica que el motor de expresión regular puede suponer que hay otros caracteres más allá del final de la cadena de asunto. Esto no debe tomarse al pie de la letra: el motor nunca intentará acceder a ningún carácter después del último del asunto.

QRegularExpression implementa este comportamiento cuando utiliza el tipo de coincidencia PartialPreferFirstMatch. Este tipo de coincidencia informa de una coincidencia parcial tan pronto como se encuentra, y no se intentan otras alternativas de coincidencia (aunque pudieran conducir a una coincidencia completa). Por ejemplo:

QRegularExpression re("abc|ab");
QRegularExpressionMatch match = re.match("ab", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

Esto sucede porque al coincidir con la primera rama del operador de alternancia se encuentra una coincidencia parcial, y por lo tanto la coincidencia se detiene, sin intentar la segunda rama. Otro ejemplo:

QRegularExpression re("abc(def)?");
QRegularExpressionMatch match = re.match("abc", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

Esto muestra lo que podría parecer un comportamiento contraintuitivo de los cuantificadores: como ? es codicioso, entonces el motor intenta primero continuar la coincidencia después de haber coincidido con "abc"; pero entonces la coincidencia llega al final de la cadena de asunto, y por lo tanto se informa de una coincidencia parcial. Esto es aún más sorprendente en el siguiente ejemplo:

QRegularExpression re("(abc)*");
QRegularExpressionMatch match = re.match("abc", 0, QRegularExpression::PartialPreferFirstMatch);
bool hasMatch = match.hasMatch(); // false
bool hasPartialMatch = match.hasPartialMatch(); // true

Es fácil entender este comportamiento si recordamos que el motor espera que la cadena de asunto sea sólo una subcadena del texto completo en el que buscamos una coincidencia (es decir, como decíamos antes, que el motor asume que hay otros caracteres más allá del final de la cadena de asunto).

Dado que el cuantificador * es codicioso, informar de una coincidencia completa podría ser un error, porque después del asunto actual "abc" puede haber otras ocurrencias de "abc". Por ejemplo, el texto completo podría haber sido "abcabcX", y por tanto la coincidencia correcta a informar (en el texto completo) habría sido "abcabc"; al coincidir sólo con el "abc" inicial obtenemos en cambio una coincidencia parcial.

Tratamiento de errores

Es posible que un objeto QRegularExpression no sea válido debido a errores de sintaxis en la cadena del patrón. La función isValid() devolverá true si la expresión regular es válida, o false en caso contrario:

QRegularExpression invalidRe("(unmatched|parenthesis");
bool isValid = invalidRe.isValid(); // false

Puede obtener más información sobre el error específico llamando a la función errorString(); además, la función patternErrorOffset() devolverá el desplazamiento dentro de la cadena de patrones

QRegularExpression invalidRe("(unmatched|parenthesis");
if (!invalidRe.isValid()) {
    QString errorString = invalidRe.errorString(); // errorString == "missing )"
    int errorOffset = invalidRe.patternErrorOffset(); // errorOffset == 22
    // ...
}

Si se intenta una coincidencia con una QRegularExpression inválida, entonces el objeto QRegularExpressionMatch devuelto tampoco será válido (es decir, su función isValid() devolverá false). Lo mismo ocurre si se intenta una coincidencia global.

Características de las expresiones regulares no compatibles con Perl

QRegularExpression no soporta todas las características disponibles en las expresiones regulares compatibles con Perl. La más notable es el hecho de que los nombres duplicados para capturar grupos no están soportados, y su uso puede llevar a un comportamiento indefinido.

Esto puede cambiar en una futura versión de Qt.

Depurando código que usa QRegularExpression

QRegularExpression utiliza internamente un compilador justo a tiempo (JIT) para optimizar la ejecución del algoritmo de concordancia. El JIT hace un uso extensivo de código auto-modificable, que puede hacer que herramientas de depuración como Valgrind se bloqueen. Debes habilitar todas las comprobaciones de código auto-modificable si quieres depurar programas usando QRegularExpression (por ejemplo, la opción de línea de comandos --smc-check de Valgrind). La desventaja de habilitar estas comprobaciones es que tu programa se ejecutará considerablemente más lento.

Para evitarlo, el JIT está deshabilitado por defecto si compilas Qt en modo depuración. Es posible anular el valor por defecto y activar o desactivar el uso del JIT (tanto en modo depuración como en modo liberación) estableciendo la variable de entorno QT_ENABLE_REGEXP_JIT a un valor distinto de cero o cero respectivamente.