En esta página

QRegularExpression Class

La clase QRegularExpression permite la coincidencia de patrones mediante expresiones regulares. Más información...

Encabezado: #include <QRegularExpression>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core

Nota: Todas las funciones de esta clase son reentrantes.

Comparaciones de QRegularExpression

CategoríaTipos comparables
igualdadQRegularExpression

Tipos públicos

enum MatchOption { NoMatchOption, AnchoredMatchOption, AnchorAtOffsetMatchOption, DontCheckSubjectStringMatchOption }
flags MatchOptions
enum MatchType { NormalMatch, PartialPreferCompleteMatch, PartialPreferFirstMatch, NoMatch }
enum PatternOption { NoPatternOption, CaseInsensitiveOption, DotMatchesEverythingOption, MultilineOption, ExtendedPatternSyntaxOption, …, UseUnicodePropertiesOption }
flags PatternOptions
(since 6.0) enum WildcardConversionOption { DefaultWildcardConversion, UnanchoredWildcardConversion, NonPathWildcardConversion }
flags WildcardConversionOptions

Funciones públicas

QRegularExpression()
QRegularExpression(const QString &pattern, QRegularExpression::PatternOptions options = NoPatternOption)
QRegularExpression(const QRegularExpression &re)
(since 6.1) QRegularExpression(QRegularExpression &&re)
~QRegularExpression()
int captureCount() const
QString errorString() const
QRegularExpressionMatchIterator globalMatch(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
(since 6.5) QRegularExpressionMatchIterator globalMatchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
bool isValid() const
QRegularExpressionMatch match(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
(since 6.5) QRegularExpressionMatch matchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const
QStringList namedCaptureGroups() const
void optimize() const
QString pattern() const
qsizetype patternErrorOffset() const
QRegularExpression::PatternOptions patternOptions() const
void setPattern(const QString &pattern)
void setPatternOptions(QRegularExpression::PatternOptions options)
void swap(QRegularExpression &other)
QRegularExpression &operator=(QRegularExpression &&re)
QRegularExpression &operator=(const QRegularExpression &re)

Miembros públicos estáticos

QString anchoredPattern(QStringView expression)
QString anchoredPattern(const QString &expression)
QString escape(QStringView str)
QString escape(const QString &str)
(since 6.0) QRegularExpression fromWildcard(QStringView pattern, Qt::CaseSensitivity cs = Qt::CaseInsensitive, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
QString wildcardToRegularExpression(QStringView pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
QString wildcardToRegularExpression(const QString &pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)
size_t qHash(const QRegularExpression &key, size_t seed = 0)
bool operator!=(const QRegularExpression &lhs, const QRegularExpression &rhs)
QDataStream &operator<<(QDataStream &out, const QRegularExpression &re)
QDebug operator<<(QDebug debug, QRegularExpression::PatternOptions patternOptions)
QDebug operator<<(QDebug debug, const QRegularExpression &re)
bool operator==(const QRegularExpression &lhs, const QRegularExpression &rhs)
QDataStream &operator>>(QDataStream &in, QRegularExpression &re)

Descripción detallada

Las expresiones regulares, o regexps, son una herramienta muy potente para manejar cadenas y textos. Esto resulta útil en muchos contextos, por ejemplo:

ValidaciónUna expresión regular puede comprobar si una subcadena cumple determinados criterios, por ejemplo, si es un número entero o si no contiene espacios en blanco.
BúsquedaUna expresión regular ofrece una coincidencia de patrones más potente que la simple coincidencia de subcadenas; por ejemplo, puede encontrar una de las palabras «mail», «letter» o «correspondence», pero ninguna de las palabras «email», «mailman», «mailer», «letterbox», etc.
Búsqueda y sustituciónUna expresión regular puede sustituir todas las apariciones de una subcadena por otra subcadena diferente; por ejemplo, sustituir todas las apariciones de «&» por «&amp;», excepto en los casos en que el símbolo «&» ya vaya seguido de un «amp;».
División de cadenasUna expresión regular se puede utilizar para identificar dónde se debe dividir una cadena, por ejemplo, para dividir cadenas delimitadas por tabulaciones.

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

Entre las buenas referencias sobre expresiones regulares se incluyen:

Introducción

QRegularExpression implementa expresiones regulares compatibles con Perl. Es totalmente compatible con Unicode. Para obtener una visión general de la sintaxis de expresiones regulares que admite QRegularExpression, consulte la página del manual pcrepattern(3) mencionada anteriormente. Una expresión regular se compone de dos elementos: una cadena de patrón y un conjunto de opciones de patrón que modifican el significado de dicha cadena.

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

QRegularExpression re("a pattern");

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

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

Ten en cuenta que, debido a las reglas de las cadenas literales de C++, debes escapar todas las barras invertidas que haya 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("\\\\");

Como alternativa, puedes utilizar un literal de cadena sin formato; en ese caso, no es necesario escapar las barras invertidas del patrón, ya que todos los caracteres comprendidos entre R"(...)" se consideran caracteres sin formato. Como puedes 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 que está establecido actualmente 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 de patrón se puede modificar estableciendo una o varias opciones de patrón. Por ejemplo, es posible configurar un patrón para que realice la coincidencia sin distinguir entre mayúsculas y minúsculas estableciendo la opción ` QRegularExpression::CaseInsensitiveOption`.

Puedes establecer las opciones pasándolas al constructor de QRegularExpression, como se muestra a continuación:

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

Como alternativa, se puede utilizar la función ` setPatternOptions()` sobre un objeto `QRegularExpressionObject` ya 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 configuradas actualmente 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 de la enumeración ` 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 de la enumeración QRegularExpression::MatchType; el algoritmo de coincidencia «tradicional» se selecciona utilizando el tipo de coincidencia NormalMatch (el valor por defecto). También es posible habilitar la coincidencia parcial de la expresión regular con una cadena objeto: consulta la sección partial matching para obtener más detalles.

Las opciones de coincidencia son un conjunto de uno o varios valores de QRegularExpression::MatchOption. Modifican la forma en que se realiza una coincidencia específica de una expresión regular con una cadena de búsqueda. Para obtener más detalles, consulte la documentación de la enumeración QRegularExpression::MatchOption.

Coincidencia normal

Para realizar una coincidencia, basta con invocar la función ` match()` pasando una cadena con la que se va a realizar la coincidencia. A esta cadena nos referimos como la «cadena objeto». El resultado de la función ` match()` es un objeto ` QRegularExpressionMatch ` que se puede utilizar para examinar los resultados de la coincidencia. 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 la coincidencia es correcta, el grupo de captura (implícito) número 0 puede utilizarse para recuperar la subcadena con la que coincide 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 objeto pasando dicho 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 subcadenas capturadas

El objeto ` QRegularExpressionMatch ` contiene también información sobre las subcadenas capturadas por los grupos de captura de la cadena de patrón. La función ` captured()` devuelve la cadena capturada por el ené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 a partir del 1, y el grupo de captura implícito 0 se utiliza para capturar la subcadena que ha coincidido con el patrón completo.

También es posible recuperar las posiciones inicial y final (dentro de la cadena de búsqueda) 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 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

La coincidencia global resulta útil para encontrar todas las apariciones de una expresión regular dada dentro de una cadena de texto. 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 similar al de Java que se puede utilizar para recorrer los resultados. Por ejemplo:

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

Dado que se trata de un iterador similar al de 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 avanzará el iterador. Siguiendo 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 puedes utilizar ` peekNext()` para obtener el siguiente resultado sin avanzar el iterador.

Asimismo, es posible utilizar simplemente el resultado de ` QRegularExpression::globalMatch ` en un bucle «for» basado en un rango, 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)) {
    // ...
}

Se puede pasar un desplazamiento inicial y una o más opciones de coincidencia a la función ` globalMatch()`, exactamente igual que en la búsqueda normal con ` match()`.

Coincidencia parcial

Se obtiene una coincidencia parcial cuando se alcanza el final de la cadena de búsqueda, pero se necesitan más caracteres para completar con éxito la coincidencia. Ten en cuenta que una coincidencia parcial suele ser mucho menos eficiente que una coincidencia normal, ya que no se pueden aplicar muchas de las optimizaciones del algoritmo de coincidencia.

Una coincidencia parcial debe solicitarse explícitamente especificando un tipo de coincidencia « 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 devuelven subcadenas capturadas, y el grupo de captura (implícito) 0, correspondiente a la coincidencia completa, captura la subcadena parcialmente coincidente de la cadena objeto.

Ten en cuenta que solicitar una coincidencia parcial puede dar lugar a una coincidencia completa, si se encuentra alguna; en este caso, ` hasMatch()` devolverá ` true ` y ` hasPartialMatch()` devolverá ` false`. Nunca ocurre que un ` QRegularExpressionMatch ` informe tanto de una coincidencia parcial como de una completa.

La coincidencia parcial resulta útil principalmente en dos casos: la validación de la entrada del usuario en tiempo real y la coincidencia incremental o 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 mantengámoslo así a efectos del ejemplo).

Nos gustaría validar la entrada con esta expresión regular mientras el usuario la escribe, de modo que podamos notificar un error en la entrada tan pronto como se valide (por ejemplo, si el usuario pulsa una tecla equivocada). Para ello, debemos distinguir tres casos:

  • la entrada no puede coincidir en ningún caso con la expresión regular;
  • la entrada sí 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.

Ten en cuenta que estos tres casos representan exactamente los estados posibles de un « QValidator » (véase la enumeración « QValidator::State »).

En concreto, en el último caso queremos que el motor de expresiones regulares informe de una coincidencia parcial: estamos haciendo coincidir con éxito el patrón con la cadena objeto, pero la coincidencia no puede continuar porque se ha alcanzado el final de la cadena objeto. Obsérvese, sin embargo, que el algoritmo de coincidencia debe continuar e intentar todas las posibilidades, y en caso de que se encuentre una coincidencia completa (no parcial), esta debe indicarse y la cadena de entrada debe aceptarse 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 la aplicación de la misma expresión regular a la cadena objeto da lugar a una coincidencia completa, esta se notifica 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 dar prioridad a una coincidencia completa frente 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 subpatrón abc\\w+X coincide parcialmente con la cadena objeto; sin embargo, el subpatrón def coincide completamente con la cadena objeto y, por lo tanto, se indica una coincidencia completa.

Si durante la búsqueda se encuentran varias coincidencias parciales (pero ninguna completa), el objeto QRegularExpressionMatch indicará 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 búsqueda incremental es otro caso de uso de la búsqueda parcial. Supongamos que queremos encontrar las apariciones de una expresión regular dentro de un texto extenso (es decir, subcadenas que coincidan con la expresión regular). Para ello, nos gustaría «introducir» el texto extenso en los motores de expresiones regulares en fragmentos más pequeños. El problema obvio es qué ocurre si la subcadena que coincide con la expresión regular se extiende a lo largo de dos o más fragmentos.

En este caso, el motor de expresiones regulares debería indicar una coincidencia parcial, de modo que podamos volver a realizar la búsqueda añadiendo nuevos datos y (eventualmente) obtener una coincidencia completa. Esto implica que el motor de expresiones regulares puede suponer que hay otros caracteres más allá del final de la cadena de búsqueda. Esto no debe interpretarse al pie de la letra: el motor nunca intentará acceder a ningún carácter posterior al último de la cadena de búsqueda.

QRegularExpression implementa este comportamiento cuando se utiliza el tipo de coincidencia « PartialPreferFirstMatch ». Este tipo de coincidencia devuelve una coincidencia parcial tan pronto como se encuentra, y no se prueban otras alternativas de coincidencia (incluso si 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 ocurre porque, al realizar la coincidencia con la primera rama del operador de alternancia, se encuentra una coincidencia parcial y, por lo tanto, la coincidencia se detiene sin probar 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: dado que « ? » es codicioso, el motor intenta primero continuar la coincidencia tras haber coincidido con « "abc" »; pero entonces la coincidencia llega al final de la cadena de sujeto y, por lo tanto, se informa de una coincidencia parcial. Esto resulta 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 comprender este comportamiento si recordamos que el motor espera que la cadena de búsqueda sea solo una subcadena del texto completo en el que buscamos una coincidencia (es decir, como dijimos antes, el motor asume que hay otros caracteres más allá del final de la cadena de búsqueda).

Dado que el cuantificador « * » es «codicioso», indicar una coincidencia completa podría ser un error, ya que después del sujeto actual "abc" puede haber otras apariciones de "abc". Por ejemplo, el texto completo podría haber sido «abcabcX», y por lo tanto la coincidencia correcta que se debería indicar (en el texto completo) habría sido "abcabc"; al comparar únicamente con la parte inicial "abc", obtenemos en cambio una coincidencia parcial.

Gestión 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

Se puede obtener más información sobre el error concreto llamando a la función ` errorString()`; además, la función ` patternErrorOffset()` devolverá la posición dentro de la cadena de patrón

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 no válida, el objeto QRegularExpressionMatch devuelto tampoco será válido (es decir, su función isValid() devolverá «false»). Lo mismo se aplica al intentar una coincidencia global.

Características de expresiones regulares compatibles con Perl no admitidas

QRegularExpression no admite todas las características disponibles en las expresiones regulares compatibles con Perl. La más destacada es que no se admiten los nombres duplicados para los grupos de captura, y su uso puede dar lugar a un comportamiento indefinido.

Esto podría cambiar en una futura versión de Qt.

Depuración de código que utiliza QRegularExpression

QRegularExpression utiliza internamente un compilador «just-in-time» (JIT) para optimizar la ejecución del algoritmo de coincidencia. El JIT hace un uso extensivo de código automodificable, lo que puede provocar que herramientas de depuración como Valgrind se cuelguen. Debes habilitar todas las comprobaciones de código automodificable si deseas depurar programas que utilicen QRegularExpression (por ejemplo, la opción de línea de comandos « --smc-check » de Valgrind). La desventaja de habilitar dichas comprobaciones es que tu programa se ejecutará considerablemente más lento.

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

Véase también QRegularExpressionMatch y QRegularExpressionMatchIterator.

Documentación sobre tipos de miembros

enum QRegularExpression::MatchOption
flags QRegularExpression::MatchOptions

ConstanteValorDescripción
QRegularExpression::NoMatchOption0x0000No hay opciones de coincidencia configuradas.
QRegularExpression::AnchoredMatchOptionAnchorAtOffsetMatchOptionUtiliza en su lugar la opción `AnchorAtOffsetMatchOption`.
QRegularExpression::AnchorAtOffsetMatchOption0x0001Para que la coincidencia sea correcta, esta debe comenzar exactamente en el desplazamiento pasado a match(), incluso si la cadena de patrón no contiene ningún metacarácter que ancle la coincidencia en ese punto. Ten en cuenta que pasar esta opción no ancla el final de la coincidencia al final de la cadena objeto; si deseas anclar completamente una expresión regular, utiliza ` anchoredPattern()`. Este valor de enumeración se ha introducido en Qt 6.0.
QRegularExpression::DontCheckSubjectStringMatchOption0x0002No se comprueba la validez UTF-16 de la cadena de búsqueda antes de intentar la coincidencia. Utiliza esta opción con extrema precaución, ya que intentar hacer coincidir una cadena no válida puede provocar un fallo del programa y/o suponer un problema de seguridad. Este valor de enumeración se introdujo en Qt 5.4.

El tipo `MatchOptions` es un `typedef` para ` QFlags<MatchOption>`. Almacena una combinación «o» de valores de `MatchOption`.

enum QRegularExpression::MatchType

La enumeración MatchType define el tipo de coincidencia que se debe intentar con la cadena objeto.

ConstanteValorDescripción
QRegularExpression::NormalMatch0Se realiza una coincidencia normal.
QRegularExpression::PartialPreferCompleteMatch1La cadena de patrón se compara parcialmente con la cadena objeto. Si se encuentra una coincidencia parcial, esta se registra y se prueban otras alternativas de coincidencia como de costumbre. Si a continuación se encuentra una coincidencia completa, esta tiene preferencia sobre la coincidencia parcial; en este caso, solo se informa de la coincidencia completa. Si, por el contrario, no se encuentra ninguna coincidencia completa (sino solo la parcial), entonces se informa de la coincidencia parcial.
QRegularExpression::PartialPreferFirstMatch2La cadena de patrón se compara parcialmente con la cadena objeto. Si se encuentra una coincidencia parcial, la búsqueda se detiene y se informa de dicha coincidencia. En este caso, no se prueban otras alternativas de coincidencia (que podrían conducir a una coincidencia completa). Además, este tipo de coincidencia asume que la cadena objeto es solo una subcadena de un texto más extenso y que (en este texto) hay otros caracteres más allá del final de la cadena objeto. Esto puede dar lugar a resultados inesperados; véase la explicación en la sección « partial matching » para obtener más detalles.
QRegularExpression::NoMatch3No se realiza ninguna coincidencia. Este valor se devuelve como tipo de coincidencia por un objeto QRegularExpressionMatch o QRegularExpressionMatchIterator creado de forma predeterminada. El uso de este tipo de coincidencia no resulta muy útil para el usuario, ya que nunca se produce ninguna coincidencia. Este valor de enumeración se ha introducido en Qt 5.1.

enum QRegularExpression::PatternOption
flags QRegularExpression::PatternOptions

La enumeración `PatternOption` define modificadores que influyen en la forma en que debe interpretarse la cadena de patrón y, por lo tanto, en la forma en que el patrón se compara con una cadena objeto.

ConstanteValorDescripción
QRegularExpression::NoPatternOption0x0000No se ha establecido ninguna opción de patrón.
QRegularExpression::CaseInsensitiveOption0x0001El patrón debe coincidir con la cadena objeto sin distinguir entre mayúsculas y minúsculas. Esta opción se corresponde con el modificador /i de las expresiones regulares de Perl.
QRegularExpression::DotMatchesEverythingOption0x0002Se permite que el metacarácter punto (.) de la cadena de patrón coincida con cualquier carácter de la cadena de búsqueda, incluidos los saltos de línea (normalmente, el punto no coincide con los saltos de línea). Esta opción se corresponde con el modificador « /s » de las expresiones regulares de Perl.
QRegularExpression::MultilineOption0x0004Se permite que los metacaracteres «caret» (^) y «dólar» ($) de la cadena de patrón coincidan, respectivamente, inmediatamente después e inmediatamente antes de cualquier salto de línea en la cadena objeto, así como al principio y al final de la misma. Esta opción se corresponde con el modificador « /m » de las expresiones regulares de Perl.
QRegularExpression::ExtendedPatternSyntaxOption0x0008Cualquier espacio en blanco de la cadena de patrón que no esté escapado y se encuentre fuera de una clase de caracteres se ignora. Además, un símbolo almohadilla (#) sin escapar fuera de una clase de caracteres hace que se ignoren todos los caracteres siguientes, hasta el primer salto de línea (incluido). Esto puede utilizarse para aumentar la legibilidad de una cadena de patrón, así como para incluir comentarios dentro de expresiones regulares; resulta especialmente útil si la cadena de patrón se carga desde un archivo o la escribe el usuario, ya que en el código C++ siempre es posible utilizar las reglas para literales de cadena a fin de colocar comentarios fuera de la cadena de patrón. Esta opción se corresponde con el modificador « /x » de las expresiones regulares de Perl.
QRegularExpression::InvertedGreedinessOption0x0010La «codicia» de los cuantificadores se invierte: *, +, ?, {m,n}, etc., pasan a ser «perezosos», mientras que sus versiones «perezosas» (*?, +?, ??, {m,n}?, etc.) pasan a ser «codiciosas». No existe ningún equivalente para esta opción en las expresiones regulares de Perl.
QRegularExpression::DontCaptureOption0x0020Los grupos de captura sin nombre no capturan subcadenas; los grupos de captura con nombre siguen funcionando según lo previsto, al igual que el grupo de captura implícito número 0, que corresponde a toda la coincidencia. No existe ningún equivalente para esta opción en las expresiones regulares de Perl.
QRegularExpression::UseUnicodePropertiesOption0x0040El significado de las clases de caracteres « \w », « \d », etc., así como el de sus homólogas («\W », « \D », etc.), cambia: en lugar de coincidir únicamente con caracteres ASCII, ahora coinciden con cualquier carácter que posea la propiedad Unicode correspondiente. Por ejemplo, « \d » pasa a coincidir con cualquier carácter que tenga la propiedad Unicode Nd (dígito decimal); « \w », con cualquier carácter que tenga la propiedad Unicode L (letra) o N (dígito), además del guión bajo, y así sucesivamente. Esta opción se corresponde con el modificador « /u » de las expresiones regulares de Perl.

El tipo PatternOptions es una definición de tipo (typedef) para QFlags<PatternOption>. Almacena una combinación OR de valores de PatternOption.

[since 6.0] enum QRegularExpression::WildcardConversionOption
flags QRegularExpression::WildcardConversionOptions

La enumeración `WildcardConversionOption` define los modificadores que influyen en la forma en que un patrón glob con caracteres comodín se convierte en un patrón de expresión regular.

ConstanteValorDescripción
QRegularExpression::DefaultWildcardConversion0x0No se ha establecido ninguna opción de conversión.
QRegularExpression::UnanchoredWildcardConversion0x1La conversión no fijará el patrón. Esto permite coincidencias parciales de cadenas en expresiones con comodines.
QRegularExpression::NonPathWildcardConversion (since Qt 6.6)0x2La conversión no interpretará el patrón como una expansión de rutas de archivo.

Esta enumeración se introdujo en Qt 6.0.

El tipo `WildcardConversionOptions` es un `typedef` para ` QFlags<WildcardConversionOption>`. Almacena una combinación «O» de valores de `WildcardConversionOption`.

Véase también QRegularExpression::wildcardToRegularExpression.

Documentación de las funciones miembro

QRegularExpression::QRegularExpression()

Crea un objeto QRegularExpression con un patrón vacío y sin opciones de patrón.

Véase también setPattern() y setPatternOptions().

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

Crea un objeto QRegularExpression utilizando el pattern proporcionado como patrón y el options como opciones del patrón.

Véase también setPattern() y setPatternOptions().

[noexcept] QRegularExpression::QRegularExpression(const QRegularExpression &re)

Crea un objeto QRegularExpression como copia de re.

Véase también operator=().

[constexpr noexcept default, since 6.1] QRegularExpression::QRegularExpression(QRegularExpression &&re)

Crea un objeto `QRegularExpression` a partir de un ` re`.

Ten en cuenta que un QRegularExpression del que se ha realizado una movida solo puede ser destruido o asignado. El efecto de llamar a otras funciones que no sean el destructor o uno de los operadores de asignación es indefinido.

Esta función se introdujo en Qt 6.1.

Véase también operator=().

[noexcept] QRegularExpression::~QRegularExpression()

Elimina el objeto « QRegularExpression ».

[static] QString QRegularExpression::anchoredPattern(QStringView expression)

Devuelve el objeto ` expression ` enmarcado entre los anclajes ` \A ` y ` \z `, que se utilizarán para la coincidencia exacta.

[static] QString QRegularExpression::anchoredPattern(const QString &expression)

Esta es una función sobrecargada.

int QRegularExpression::captureCount() const

Devuelve el número de grupos de captura que hay dentro de la cadena del patrón, o -1 si la expresión regular no es válida.

Nota: El grupo de captura implícito 0 no se incluye en el número devuelto.

Véase también isValid().

QString QRegularExpression::errorString() const

Devuelve una descripción textual del error detectado al comprobar la validez de la expresión regular, o «sin error» si no se ha detectado ningún error.

Véase también isValid() y patternErrorOffset().

[static] QString QRegularExpression::escape(QStringView str)

Escapa todos los caracteres de str para que dejen de tener cualquier significado especial cuando se utilicen como cadena de patrón de expresión regular, y devuelve la cadena escapada. Por ejemplo:

QString escaped = QRegularExpression::escape("a(x) = f(x) + g(x)");
// escaped == "a\\(x\\)\\ \\=\\ f\\(x\\)\\ \\+\\ g\\(x\\)"

Esto resulta muy útil para construir patrones a partir de cadenas arbitrarias:

QString pattern = "(" + QRegularExpression::escape(name) +
                "|" + QRegularExpression::escape(nickname) + ")";
QRegularExpression re(pattern);

Nota: Esta función implementa el algoritmo «quotemeta» de Perl y escapa con una barra invertida todos los caracteres de str, excepto los caracteres de los rangos [A-Z], [a-z] y [0-9], así como el carácter de guión bajo (_). La única diferencia con respecto a Perl es que un carácter NUL literal dentro de « str » se escapa con la secuencia « "\\0" » (barra invertida + '0'), en lugar de « "\\\0" » (barra invertida + NUL).

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

Esta es una función sobrecargada.

[static, since 6.0] QRegularExpression QRegularExpression::fromWildcard(QStringView pattern, Qt::CaseSensitivity cs = Qt::CaseInsensitive, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)

Devuelve una expresión regular del patrón glob pattern. La expresión regular distinguirá entre mayúsculas y minúsculas si cs es Qt::CaseSensitive, y se convertirá según options.

Equivalente a

auto reOptions = cs == Qt::CaseSensitive ? QRegularExpression::NoPatternOption :
                                           QRegularExpression::CaseInsensitiveOption;
return QRegularExpression(wildcardToRegularExpression(str, options), reOptions);

Esta función se introdujo en Qt 6.0.

QRegularExpressionMatchIterator QRegularExpression::globalMatch(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const

Intenta realizar una coincidencia global de la expresión regular con la cadena « subject » dada, comenzando en la posición « offset » dentro del texto de búsqueda, utilizando una coincidencia de tipo « matchType » y respetando el valor dado en « matchOptions ».

El valor devuelto QRegularExpressionMatchIterator se sitúa antes del primer resultado de la búsqueda (si lo hay).

Véase también QRegularExpressionMatchIterator y global matching.

[since 6.5] QRegularExpressionMatchIterator QRegularExpression::globalMatchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const

Intenta realizar una coincidencia global de la expresión regular con la vista de cadena dada subjectView, comenzando en la posición offset dentro del texto de búsqueda, utilizando una coincidencia de tipo matchType y respetando el valor dado matchOptions.

El QRegularExpressionMatchIterator devuelto se sitúa antes del primer resultado de la coincidencia (si lo hay).

Nota: Los datos a los que hace referencia subjectView deben seguir siendo válidos mientras haya objetos QRegularExpressionMatchIterator o QRegularExpressionMatch que los utilicen.

Esta función se introdujo en Qt 6.5.

Véase también QRegularExpressionMatchIterator y global matching.

bool QRegularExpression::isValid() const

Devuelve « true » si la expresión regular es válida (es decir, no contiene errores de sintaxis, etc.), o «false» en caso contrario. Utiliza « errorString()» para obtener una descripción textual del error.

Véase también errorString() y patternErrorOffset().

QRegularExpressionMatch QRegularExpression::match(const QString &subject, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const

Intenta hacer coincidir la expresión regular con la cadena « subject » dada, comenzando en la posición « offset » dentro del texto, utilizando un tipo de coincidencia « matchType » y respetando el valor dado « matchOptions ».

El objeto QRegularExpressionMatch devuelto contiene los resultados de la coincidencia.

Véase también QRegularExpressionMatch y normal matching.

[since 6.5] QRegularExpressionMatch QRegularExpression::matchView(QStringView subjectView, qsizetype offset = 0, QRegularExpression::MatchType matchType = NormalMatch, QRegularExpression::MatchOptions matchOptions = NoMatchOption) const

Intenta hacer coincidir la expresión regular con la vista de cadena « subjectView » proporcionada, comenzando en la posición « offset » dentro del texto de búsqueda, utilizando un tipo de coincidencia « matchType » y respetando el valor « matchOptions » proporcionado.

El objeto QRegularExpressionMatch devuelto contiene los resultados de la coincidencia.

Nota: Los datos a los que hace referencia subjectView deben seguir siendo válidos mientras haya objetos QRegularExpressionMatch que los utilicen.

Esta función se introdujo en Qt 6.5.

Véase también QRegularExpressionMatch y normal matching.

QStringList QRegularExpression::namedCaptureGroups() const

Devuelve una lista de captureCount() + 1 elementos, que contiene los nombres de los grupos de captura con nombre de la cadena de patrón. La lista está ordenada de tal forma que el elemento de la lista situado en la posición i es el nombre del i-ésimo grupo de captura, si tiene nombre, o una cadena vacía si dicho grupo de captura no tiene nombre.

Por ejemplo, dada la expresión regular

    (?<day>\d\d)-(?<month>\d\d)-(?<year>\d\d\d\d) (\w+) (?<name>\w+)

namedCaptureGroups() devolverá la siguiente lista:

    ("", "day", "month", "year", "", "name")

lo que se debe a que el grupo de captura n.º 0 (que corresponde a toda la coincidencia) no tiene nombre, el grupo de captura n.º 1 se llama «day», el grupo de captura n.º 2 se llama «month», etc.

Si la expresión regular no es válida, devuelve una lista vacía.

Véase también isValid(), QRegularExpressionMatch::captured() y QString::isEmpty().

void QRegularExpression::optimize() const

Compila el patrón de forma inmediata, lo que incluye su compilación JIT (si el JIT está activado) con fines de optimización.

Véase también isValid() y Debugging Code that Uses QRegularExpression.

QString QRegularExpression::pattern() const

Devuelve la cadena de patrón de la expresión regular.

Véase también setPattern() y patternOptions().

qsizetype QRegularExpression::patternErrorOffset() const

Devuelve el desplazamiento, dentro de la cadena del patrón, en el que se encontró un error al comprobar la validez de la expresión regular. Si no se encontró ningún error, se devuelve -1.

Véase también pattern(), isValid() y errorString().

QRegularExpression::PatternOptions QRegularExpression::patternOptions() const

Devuelve las opciones del patrón para la expresión regular.

Véase también setPatternOptions() y pattern().

void QRegularExpression::setPattern(const QString &pattern)

Establece la cadena de patrón de la expresión regular en pattern. Las opciones del patrón no se modifican.

Véase también ` pattern()` y ` setPatternOptions()`.

void QRegularExpression::setPatternOptions(QRegularExpression::PatternOptions options)

Establece el options especificado como opciones de patrón de la expresión regular. La cadena del patrón no se modifica.

Véase también patternOptions() y setPattern().

[noexcept] void QRegularExpression::swap(QRegularExpression &other)

Sustituye esta expresión regular por « other ». Esta operación es muy rápida y nunca falla.

[static] QString QRegularExpression::wildcardToRegularExpression(QStringView pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)

Devuelve una representación en forma de expresión regular del patrón glob dado pattern.

Hay dos transformaciones posibles: una dirigida a la expansión de rutas de archivo y otra más genérica.

Por defecto, la transformación se centra en el glob de rutas de archivo, lo que significa, en particular, que los separadores de ruta reciben un tratamiento especial. Esto implica que no se trata simplemente de una conversión básica de «*» a «.*» y similares.

QString wildcard = QRegularExpression::wildcardToRegularExpression("*.jpeg");
// Will match files with names like:
//    foo.jpeg
//    f_o_o.jpeg
//    föö.jpeg

La transformación de globbing más genérica está disponible pasando NonPathWildcardConversion en la conversión options.

Esta implementación sigue fielmente la definición de comodines para patrones glob:

cCualquier carácter representa a sí mismo, salvo los que se mencionan a continuación. Por lo tanto, c coincide con el carácter c.
?Coincide con cualquier carácter único, excepto con un separador de ruta (en caso de que se haya seleccionado el globbing de rutas de archivos). Es lo mismo que b{.} en expresiones regulares completas.
*Coincide con cero o más caracteres cualesquiera, excepto los separadores de ruta (en caso de que se haya seleccionado la expansión de rutas de archivos). Es equivalente a .* en expresiones regulares completas.
[abc]Coincide con un carácter de los indicados entre corchetes.
[a-c]Coincide con un carácter del rango indicado entre corchetes.
[!abc]Coincide con un carácter que no se encuentre entre corchetes. Equivale a [^abc] en una expresión regular completa.
[!a-c]Coincide con un carácter que no pertenezca al rango indicado entre corchetes. Es equivalente a [^a-c] en expresiones regulares completas.

Nota: Por razones históricas, el carácter de barra invertida (\) no es un carácter de escape en este contexto. Para buscar uno de los caracteres especiales, colócalo entre corchetes (por ejemplo, [?]).

Se puede encontrar más información sobre la implementación en:

Por defecto, la expresión regular devuelta está totalmente anclada. En otras palabras, no es necesario volver a llamar a anchoredPattern() sobre el resultado. Para obtener una expresión regular que no esté anclada, pasa UnanchoredWildcardConversion en la conversión options.

Véase también escape().

[static] QString QRegularExpression::wildcardToRegularExpression(const QString &pattern, QRegularExpression::WildcardConversionOptions options = DefaultWildcardConversion)

Esta es una función sobrecargada.

[noexcept] QRegularExpression &QRegularExpression::operator=(QRegularExpression &&re)

La función «move» asigna la expresión regular re a este objeto y devuelve una referencia al resultado. Se copian tanto el patrón como las opciones del patrón.

Tenga en cuenta que una expresión regular QRegularExpression de la que se ha realizado una asignación por movimiento solo puede ser destruida o asignada. El efecto de llamar a otras funciones que no sean el destructor o uno de los operadores de asignación es indefinido.

[noexcept] QRegularExpression &QRegularExpression::operator=(const QRegularExpression &re)

Asigna la expresión regular re a este objeto y devuelve una referencia a la copia. Se copian tanto el patrón como las opciones del patrón.

Elementos no miembros relacionados

[noexcept] size_t qHash(const QRegularExpression &key, size_t seed = 0)

Devuelve el valor hash de key, utilizando seed como semilla para el cálculo.

[noexcept] bool operator!=(const QRegularExpression &lhs, const QRegularExpression &rhs)

Devuelve « true » si la expresión regular « lhs » es diferente de « rhs », o «false» en caso contrario.

Véase también operator==().

QDataStream &operator<<(QDataStream &out, const QRegularExpression &re)

Escribe la expresión regular re en el flujo out.

Véase también «Serialización detipos de datos de Qt».

QDebug operator<<(QDebug debug, QRegularExpression::PatternOptions patternOptions)

Escribe las opciones del patrón patternOptions en el objeto de depuración debug con fines de depuración.

Véase también «Técnicas de depuración».

QDebug operator<<(QDebug debug, const QRegularExpression &re)

Escribe la expresión regular « re » en el objeto de depuración « debug » con fines de depuración.

Véase también «Técnicas de depuración».

[noexcept] bool operator==(const QRegularExpression &lhs, const QRegularExpression &rhs)

Devuelve ` true ` si la expresión regular ` lhs ` es igual a ` rhs`, o `false` en caso contrario. Dos objetos ` QRegularExpression ` son iguales si tienen la misma cadena de patrón y las mismas opciones de patrón.

Véase también operator!=().

QDataStream &operator>>(QDataStream &in, QRegularExpression &re)

Lee una expresión regular del flujo in y la guarda en re.

Véase también «Serialización detipos de datos de Qt».

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.