QRegExp Class

Description détaillée

Cette classe est obsolète dans Qt 6. Veuillez utiliser QRegularExpression à la place pour tout nouveau code. Pour obtenir des conseils sur le portage de l'ancien code de QRegExp vers QRegularExpression, consultez Porting to QRegularExpression.

Une expression régulière, ou « regexp », est un modèle permettant de rechercher des sous-chaînes dans un texte. Elle s'avère utile dans de nombreux contextes, par exemple :

Vous trouverez ici une brève introduction aux expressions régulières, une description du langage d'expressions régulières de Qt, quelques exemples, ainsi que la documentation relative aux fonctions. QRegExp s’inspire du langage d’expressions régulières de Perl. Il prend entièrement en charge Unicode. QRegExp peut également être utilisé dans un mode plus simple, à base de caractères génériques, similaire aux fonctionnalités disponibles dans les interpréteurs de commandes. Les règles syntaxiques utilisées par QRegExp peuvent être modifiées à l’aide de ` setPatternSyntax()` (). En particulier, la syntaxe du motif peut être définie sur ` QRegExp::FixedString`, ce qui signifie que le motif à faire correspondre est interprété comme une chaîne de caractères simple, c’est-à-dire que les caractères spéciaux (par exemple, la barre oblique inversée) ne sont pas échappés.

Un ouvrage de référence sur les expressions régulières est *Mastering Regular Expressions* (troisième édition) de Jeffrey E. F. Friedl, ISBN 0-596-52812-4.

Considérations relatives à la sécurité

QRegExp n'impose aucune limite aux ressources qu'un motif peut consommer, et la taille de ses tampons internes peut entraîner un débordement. Un motif spécialement conçu, même relativement petit, peut donc épuiser la mémoire disponible, provoquer un débordement de la pile ou corrompre la mémoire. Ce phénomène se produit lors de la compilation du motif, c'est-à-dire dès que celui-ci est assigné, et ne nécessite aucune correspondance avec du texte. Il en va de même pour les motifs de type ` wildcard `, qui sont traduits en interne en expressions régulières.

N’utilisez QRegExp qu’avec des motifs provenant d’une source fiable. Privilégiez plutôt l’utilisation d’ QRegularExpression, qui limite les ressources qu’une correspondance peut consommer.

Introduction

Les expressions régulières sont constituées d'expressions, de quantificateurs et d'assertions. L'expression la plus simple est un caractère, par exemple x ou 5. Une expression peut également être un ensemble de caractères entre crochets. [ABCD] correspondra à un A, un B, un C ou un D. On peut écrire cette même expression sous la forme [A-D], et une expression permettant de trouver n'importe quelle lettre majuscule de l'alphabet anglais s'écrit [A-Z].

Un quantificateur spécifie le nombre d’occurrences d’une expression qui doivent être trouvées. x{1,1} signifie trouver un et un seul x. x{1,5} signifie trouver une séquence de caractères x contenant au moins un x mais pas plus de cinq.

Notez qu’en général, les expressions régulières ne peuvent pas être utilisées pour vérifier l’équilibre des parenthèses ou des balises. Par exemple, on peut écrire une expression régulière pour faire correspondre une balise d’ouverture HTML <b> et sa balise de fermeture </b>, si les balises <b> ne sont pas imbriquées ; mais si les balises <b> sont imbriquées, cette même expression régulière fera correspondre une balise d’ouverture <b> avec la balise de fermeture erronée </b>. Pour le fragment <b>bold <b>bolder</b></b>, le premier <b> serait mis en correspondance avec le premier </b>, ce qui n’est pas correct. Il est toutefois possible d’écrire une expression régulière qui fera correspondre correctement des crochets ou des balises imbriqués, mais uniquement si le nombre de niveaux d’imbrication est fixe et connu. Si le nombre de niveaux d’imbrication n’est ni fixe ni connu, il est impossible d’écrire une expression régulière qui ne rencontrera pas d’échec.

Supposons que nous souhaitions une expression régulière pour trouver des nombres entiers compris entre 0 et 99. Au moins un chiffre étant requis, nous commençons par l’expression [0-9]{1,1}, qui correspond à un seul chiffre exactement une fois. Cette expression régulière trouve les nombres entiers compris entre 0 et 9. Pour faire correspondre des nombres entiers allant jusqu’à 99, il faut augmenter le nombre maximal d’occurrences à 2 ; l’expression régulière devient alors [0-9]{1,2}. Cette expression régulière répond à l’exigence initiale de faire correspondre des nombres entiers compris entre 0 et 99, mais elle fera également correspondre des nombres entiers apparaissant au milieu de chaînes de caractères. Si l'on souhaite que le nombre entier trouvé corresponde à la chaîne entière, il faut utiliser les ancrages ^ (caret) et $ (dollar). Lorsque ^ est le premier caractère d'une expression régulière, cela signifie que celle-ci doit correspondre dès le début de la chaîne. Lorsque $ est le dernier caractère de l’expression régulière, cela signifie que celle-ci doit correspondre jusqu’à la fin de la chaîne. L’expression régulière devient alors ^[0-9]{1,2}$. Notez que les ancrages, tels que ^ et $, ne correspondent pas à des caractères, mais à des emplacements dans la chaîne.

Si vous avez déjà vu des expressions régulières décrites ailleurs, elles pouvaient sembler différentes de celles présentées ici. En effet, certains ensembles de caractères et certains quantificateurs sont si courants qu’on leur a attribué des symboles spéciaux pour les représenter. [0-9] peut être remplacé par le symbole \d. Le quantificateur permettant de faire correspondre exactement une occurrence, {1,1}, peut être remplacé par l’expression elle-même ; ainsi, x{1,1} équivaut à x. Notre expression régulière pour les nombres de 0 à 99 pourrait donc s’écrire ^\d{1,2}$. On peut également l'écrire ^\d\d {0,1}$, c'est-à-dire : à partir du début de la chaîne, rechercher un chiffre suivi immédiatement de 0 ou 1 chiffre. En pratique, on l'écrirait ^\d\d ?$. Le caractère « ? » est une abréviation du quantificateur {0,1}, c'est-à-dire 0 ou 1 occurrence. Le « ? » rend l'expression facultative. L'expression régulière ^\d\d ?$ signifie : à partir du début de la chaîne, rechercher un chiffre, suivi immédiatement de 0 ou 1 autre chiffre, suivi immédiatement de la fin de la chaîne.

Pour écrire une expression régulière qui corresponde à l’un des mots « mail » , « letter » ou « correspondence », mais qui ne corresponde pas aux mots contenant ces termes, par exemple « email », « mailman », « mailer » et « letterbox », commencez par une expression régulière correspondant à « mail ». Exprimée en entier, l’expression régulière est m{1,1}a{1,1}i{1,1}l{1,1}, mais comme une expression de caractère est automatiquement quantifiée par {1,1}, nous pouvons simplifier l’expression régulière en « mail », c’est-à-dire un « m » suivi d’un « a », puis d’un « i » et enfin d’un « l ». Nous pouvons désormais utiliser la barre verticale |, qui signifie « ou », pour inclure les deux autres mots ; ainsi, notre expression régulière permettant de trouver l’un des trois mots devient mail|letter|correspondence. Rechercher « mail » , « letter » ou « correspondence ». Bien que cette expression régulière corresponde à l’un des trois mots que nous souhaitons trouver, elle correspondra également à des mots que nous ne souhaitons pas trouver, par exemple « email ». Pour empêcher l’expression régulière de correspondre à des mots indésirables, nous devons lui indiquer de commencer et de terminer la correspondance aux limites des mots. Tout d’abord, nous plaçons notre expression régulière entre parenthèses : (mail|letter|correspondence). Les parenthèses regroupent des expressions et identifient une partie de l’expression régulière que nous souhaitons capture. En plaçant l’expression entre parenthèses, nous pouvons l’utiliser comme composant dans des expressions régulières plus complexes. Cela nous permet également de vérifier lequel des trois mots a effectivement été trouvé. Pour forcer la correspondance à commencer et à se terminer sur des limites de mots, nous encadrons l’expression régulière par \b assertions de limite de mot: \b(mail|letter|correspondance)\b. Désormais, l’expression régulière signifie : trouver une limite de mot, suivie de l’expression régulière entre parenthèses, puis d’une limite de mot. L’ \b assertion correspond à une position dans l’expression régulière, et non à un caractère. Une limite de mot est tout caractère n’appartenant pas à un mot, par exemple un espace, un saut de ligne, ou le début ou la fin d’une chaîne.

Si nous voulons remplacer les caractères « & » par l’entité HTML &, l’expression régulière à utiliser est simplement &. Mais cette expression régulière correspondra également aux « & » qui ont déjà été convertis en entités HTML. Nous souhaitons ne remplacer que les « & » qui ne sont pas déjà suivis de « amp; ». Pour cela, nous avons besoin de l’assertion de regard en avant négatif, (?!__). L’expression régulière peut alors s’écrire &(?!amp;), c’est-à-dire : trouver un « & » qui n’ est pas suivi de « amp; ».

Si nous voulons compter toutes les occurrences de « Eric » et « Eirik » dans une chaîne, deux solutions valides sont \b(Eric|Eirik)\b et \bEi?ri[ck]\b. L’assertion de limite de mot «\b » est nécessaire pour éviter de faire correspondre des mots contenant l’un ou l’autre de ces noms, par exemple « Ericsson ». Notez que la deuxième expression régulière correspond à plus de variantes orthographiques que nous ne le souhaitons : « Eric », « Erik », « Eiric » et « Eirik ».

Certains des exemples évoqués ci-dessus sont mis en œuvre dans la section « code examples ».

Caractères et abréviations pour les ensembles de caractères

Remarque : le compilateur C++ transforme les barres obliques inversées dans les chaînes de caractères. Pour inclure un \ dans une expression régulière, saisissez-le deux fois, c'est-à-dire \\. Pour faire correspondre le caractère barre oblique inversée lui-même, saisissez-le quatre fois, c'est-à-dire \\\\.

Ensembles de caractères

Les crochets signifient qu’il faut rechercher n’importe quel caractère contenu entre ces crochets. Les abréviations d’ensembles de caractères décrites ci-dessus peuvent apparaître dans un ensemble de caractères entre crochets. À l’exception des abréviations d’ensembles de caractères et des deux exceptions suivantes, les caractères n’ont pas de signification particulière entre crochets.

L'utilisation des abréviations de jeux de caractères prédéfinis est plus portable que l'utilisation de plages de caractères d'une plateforme ou d'un langage à l'autre. Par exemple, [0-9] correspond à un chiffre des alphabets occidentaux, mais \d correspond à un chiffre dans n'importe quel alphabet.

Remarque : dans d'autres documentations sur les expressions régulières, les ensembles de caractères sont souvent appelés « classes de caractères ».

Quantificateurs

Par défaut, une expression est automatiquement quantifiée par {1,1}, c'est-à-dire qu'elle doit apparaître exactement une fois. Dans la liste suivante, E désigne une expression. Une expression est un caractère, une abréviation d'un ensemble de caractères, un ensemble de caractères entre crochets ou une expression entre parenthèses.

Pour appliquer un quantificateur à plus que le caractère précédent, utilisez des parenthèses afin de regrouper des caractères dans une expression. Par exemple, tag+ correspond à un « t » suivi d'un « a » puis d'au moins un « g », tandis que (tag)+ correspond à au moins une occurrence de « tag ».

Remarque : les quantificateurs sont normalement « gourmands ». Ils font toujours correspondre autant de texte que possible. Par exemple, 0+ correspond au premier zéro trouvé et à tous les zéros consécutifs qui suivent ce premier zéro. Appliqué à « 20005 », il correspond à «20005». Il est possible de rendre les quantificateurs non gourmands ; voir setMinimal().

Capture de texte

Les parenthèses nous permettent de regrouper des éléments afin de pouvoir les quantifier et les capturer. Par exemple, si nous avons l’expression ` mail|letter|correspondence ` qui correspond à une chaîne, nous savons qu’un de ces mots a été trouvé, mais pas lequel. L'utilisation de parenthèses nous permet de « capturer » tout ce qui est mis en correspondance entre leurs limites ; ainsi, si nous utilisons (mail|letter|correspondence) et que nous comparons cette expression régulière à la chaîne « I sent you some email », nous pouvons utiliser les fonctions cap() ou capturedTexts() pour extraire les caractères mis en correspondance, en l'occurrence « mail ».

Nous pouvons utiliser le texte capturé au sein même de l’expression régulière. Pour faire référence au texte capturé, nous utilisons des références arrière qui sont indexées à partir de 1, comme pour la fonction cap(). Par exemple, nous pourrions rechercher des mots en double dans une chaîne à l’aide de `\b` : `(\w)` `\W)` `\1 ` ` \b `, ce qui signifie : trouver une limite de mot suivie d’un ou plusieurs caractères de mot, suivie d’un ou plusieurs caractères non-mot, suivie du même texte que la première expression entre parenthèses, suivie d’une limite de mot.

Si l'on souhaite utiliser les parenthèses uniquement à des fins de regroupement et non de capture, on peut recourir à la syntaxe sans capture, par exemple (?:green|blue). Les parenthèses sans capture commencent par « (?: » et se terminent par « ) ». Dans cet exemple, nous recherchons soit « green », soit « blue », mais nous ne capturons pas le résultat ; nous savons donc uniquement si la correspondance a eu lieu ou non, sans connaître la couleur réellement trouvée. L’utilisation de parenthèses sans capture est plus efficace que celle de parenthèses avec capture, car le moteur d’expressions régulières a moins de travail de gestion à effectuer.

Les parenthèses avec et sans capture peuvent toutes deux être imbriquées.

Pour des raisons historiques, les quantificateurs (par exemple *) qui s’appliquent aux parenthèses capturantes sont plus « gourmands » que les autres quantificateurs. Par exemple, a*(a*) correspondra à « aaa » avec cap(1) == « aaa ». Ce comportement diffère de celui d’autres moteurs d’expressions régulières (notamment Perl). Pour obtenir un comportement de capture plus intuitif, spécifiez l’ QRegExp::RegExp2 e au constructeur QRegExp ou appelez la fonction setPatternSyntax(QRegExp::RegExp2).

Lorsque le nombre de correspondances ne peut pas être déterminé à l’avance, une pratique courante consiste à utiliser ` cap()` dans une boucle. Par exemple :

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"]

Affirmations

Les assertions fournissent des informations sur le texte à l'endroit où elles apparaissent dans l'expression régulière, mais elles ne correspondent à aucun caractère. Dans la liste suivante, E représente n'importe quelle expression.

Correspondance avec des caractères génériques

La plupart des shells de commande, tels que bash ou cmd.exe, prennent en charge le « file globbing », c’est-à-dire la possibilité d’identifier un groupe de fichiers à l’aide de caractères génériques. La fonction setPatternSyntax() permet de basculer entre le mode expression régulière et le mode caractères génériques. La correspondance par caractères génériques est beaucoup plus simple que les expressions régulières complètes et ne comporte que quatre fonctionnalités :

En mode « Wildcard », les caractères génériques ne peuvent pas être échappés. En mode « WildcardUnix », le caractère « \ » échappe le caractère générique.

Par exemple, si nous sommes en mode « Wildcard » et que nous avons des chaînes contenant des noms de fichiers, nous pourrions identifier les fichiers HTML avec *.html. Cela correspondra à zéro ou plusieurs caractères suivis d'un point, puis des lettres « h », « t », « m » et « l ».

Pour vérifier si une chaîne correspond à une expression avec caractères génériques, utilisez la fonction ` exactMatch()`. Par exemple :

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

Remarques à l'attention des utilisateurs de Perl

La plupart des abréviations de classes de caractères prises en charge par Perl le sont également par QRegExp ; voir characters and abbreviations for sets of characters.

Dans QRegExp, sauf au sein des classes de caractères, « ^ » désigne toujours le début de la chaîne ; il faut donc toujours échapper le caractère « ^ » (caret), sauf s'il est utilisé à cette fin. En Perl, la signification du caractère « ^ » varie automatiquement en fonction de son emplacement ; il est donc rarement nécessaire de l'échapper. Il en va de même pour « $ », qui, dans QRegExp, désigne toujours la fin de la chaîne.

Les quantificateurs de QRegExp sont identiques aux quantificateurs « gourmands » de Perl (mais voir la section « note above »). La correspondance non gourmande ne peut pas être appliquée à des quantificateurs individuels, mais peut l’être à l’ensemble des quantificateurs du motif. Par exemple, pour reproduire l’expression régulière Perl ro+?m, il faut écrire :

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

L'équivalent de l'option « /i » de Perl est « setCaseSensitivity » (Qt::CaseInsensitive).

L'option « /g » de Perl peut être émulée à l'aide d'un « loop ».

Dans QRegExp , . correspond à n'importe quel caractère ; par conséquent, toutes les expressions régulières QRegExp disposent d'un équivalent à l'option « /s » de Perl. QRegExp ne dispose pas d'équivalent à l'option « /m » de Perl, mais celle-ci peut être émulée de différentes manières, par exemple en divisant l'entrée en lignes ou en effectuant une boucle avec une expression régulière qui recherche les sauts de ligne.

QRegExp étant orienté chaînes de caractères, il n’existe pas d’assertions de type \A, \Z ou \z. L’assertion \G n’est pas prise en charge, mais peut être simulée à l’aide d’une boucle.

La variable $& de Perl correspond à cap(0) ou capturedTexts()[0]. Il n’existe pas d’équivalents QRegExp pour $`, $' ou $+. Les variables de capture de Perl, $1, $2, …, correspondent à cap(1) ou capturedTexts()[1], cap(2) ou capturedTexts()[2], etc.

Pour remplacer un motif, utilisez QString::replace().

La syntaxe étendue des expressions régulières de Perl n’est pas prise en charge, pas plus que les directives, par exemple (?i), ou les commentaires d’ /x s régulières, par exemple (?#comment). En revanche, les règles du C++ relatives aux chaînes littérales peuvent être utilisées pour obtenir le même résultat :

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

Les assertions d'anticipation positive et négative de largeur nulle (?=motif) et (?!motif) sont prises en charge avec la même syntaxe que dans Perl. Les assertions de rétrospection de Perl, les sous-expressions « indépendantes » et les expressions conditionnelles ne sont pas prises en charge.

Les parenthèses sans capture sont également prises en charge, avec la même syntaxe (?:motif).

Voir QString::split() et QStringList::join() pour les équivalents des fonctions split et join de Perl.

Remarque : comme le C++ transforme les \', ceux-ci doivent être écrits deux fois dans le code, par exemple \b doit s'écrire \\b.

Exemples de code

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)

La troisième chaîne correspond à «6 ». Il s'agit d'une expression régulière simple permettant de valider des nombres entiers compris entre 0 et 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)

La deuxième chaîne correspond à «This_is-OK ». Nous avons utilisé l'abréviation du jeu de caractères «\S » (sans espace) et les ancres pour trouver les chaînes ne contenant aucun espace.

Dans l'exemple suivant, nous recherchons des chaînes contenant « mail », « letter » ou « correspondence », mais uniquement des mots entiers, c'est-à-dire pas « 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

La deuxième chaîne correspond à « Please write the letter ». Le mot « letter » est également capturé (grâce aux parenthèses). Nous pouvons voir le texte que nous avons capturé comme suit :

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

Cela permettra de capturer le texte contenu entre la première paire de parenthèses de capture (en comptant les parenthèses de capture gauches de gauche à droite). Les parenthèses sont numérotées à partir de 1, car cap(0) correspond à l’expression régulière entière mise en correspondance (ce qui équivaut à « & » dans la plupart des moteurs d’expressions régulières).

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"

Ici, nous avons transmis l’objet QRegExp à la fonction replace() de QString afin de remplacer le texte correspondant par un nouveau texte.

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

Nous avons utilisé la fonction indexIn() pour rechercher de manière répétée l’expression régulière dans la chaîne. Notez qu’au lieu d’avancer d’un caractère à la fois pos++, nous aurions pu écrire pos += rx.matchedLength() pour ignorer la partie de la chaîne déjà trouvée. Le nombre de occurrences sera égal à 3, correspondant à « One Eric another Eirik, and an Ericsson. Combien d’Eiriks, Eric? » ; il ne correspond pas à « Ericsson » ni à « Eiriks », car ces termes ne sont pas délimités par des limites de non-mots.

L’une des utilisations courantes des expressions régulières consiste à fractionner des lignes de données délimitées en leurs champs constitutifs.

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);
}

Dans cet exemple, nos lignes d’entrée se présentent sous la forme : nom de l’entreprise, adresse web et pays. Malheureusement, l’expression régulière est assez longue et peu polyvalente : le code cessera de fonctionner si nous ajoutons d’autres champs. Une solution plus simple et plus efficace consiste à rechercher le séparateur, «\t » dans ce cas précis, et à extraire le texte qui l'entoure. La fonction QString::split() peut prendre comme argument une chaîne de caractères ou une expression régulière servant de séparateur, et diviser une chaîne en conséquence.

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

Ici, field[0] correspond au nom de l'entreprise, field[1] à l'adresse web, et ainsi de suite.

Pour imiter le comportement d’un shell, on peut utiliser le mode « caractères génériques ».

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

La correspondance avec des caractères génériques peut être pratique en raison de sa simplicité, mais toute expression régulière utilisant des caractères génériques peut être définie à l’aide d’expressions régulières complètes, par exemple .*\.html$. Notez que nous ne pouvons pas faire correspondre à la fois les fichiers .html et .htm avec un caractère générique, à moins d'utiliser *.htm*, ce qui fera également correspondre « test.html.bak ». Une expression régulière complète nous offre la précision dont nous avons besoin : .*\.html?$.

QRegExp peut effectuer des correspondances sans distinction de casse à l’aide de ` setCaseSensitivity()` et peut utiliser une correspondance non gourmande, voir ` setMinimal()`. Par défaut, QRegExp utilise des expressions régulières complètes, mais cela peut être modifié avec ` setPatternSyntax()`. La recherche peut s’effectuer vers l’avant avec ` indexIn()` ou vers l’arrière avec ` lastIndexIn()`. On peut accéder au texte capturé à l’aide de capturedTexts(), qui renvoie une liste de toutes les chaînes capturées, ou à l’aide de cap(), qui renvoie la chaîne capturée correspondant à l’index donné. La fonction pos() prend un index de correspondance et renvoie la position dans la chaîne où la correspondance a été trouvée (ou -1 s’il n’y a pas eu de correspondance).

Portage vers QRegularExpression

La classe ` QRegularExpression `, introduite dans Qt 5, implémente des expressions régulières compatibles avec Perl et constitue une amélioration considérable par rapport à `QRegExp` en termes d’API proposées, de syntaxe de motifs prise en charge et de vitesse d’exécution. La principale différence réside dans le fait qu’ QRegularExpression se contente de contenir une expression régulière et n’ est pas modifiée lorsqu’une correspondance est demandée. À la place, un objet QRegularExpressionMatch est renvoyé, permettant de vérifier le résultat de la correspondance et d’extraire la sous-chaîne capturée. Il en va de même pour la correspondance globale et QRegularExpressionMatchIterator.

D'autres différences sont présentées ci-dessous.

Syntaxe différente des motifs

Le portage d'une expression régulière de QRegExp vers QRegularExpression peut nécessiter des modifications du motif lui-même.

Dans certains cas précis, QRegExp était trop tolérant et acceptait des motifs qui sont tout simplement invalides avec l’ QRegularExpression. Ceux-ci sont faciles à détecter, car les objets QRegularExpression créés à partir de ces motifs ne sont pas valides (voir QRegularExpression::isValid()).

Dans d’autres cas, un motif porté de QRegExp vers QRegularExpression peut modifier silencieusement la sémantique. Il est donc nécessaire de revoir les motifs utilisés. Les cas les plus notables d’incompatibilité silencieuse sont les suivants :

• Des accolades sont nécessaires pour utiliser une échappement hexadécimal tel que \xHHHH comportant plus de 2 chiffres. Un motif tel que \x2022 doit être porté vers \x{2022}, sinon il correspondra à un espace (0x20) suivi de la chaîne "22". En général, il est fortement recommandé de toujours utiliser des accolades avec l’échappement \x, quel que soit le nombre de chiffres spécifié.
• Une quantification de 0 à n telle que {,n} doit être convertie en {0,n} pour préserver la sémantique. Sinon, un motif tel que \d{,3} correspondrait à un chiffre suivi de la chaîne exacte "{,3}".
• Par défaut, QRegExp effectue une correspondance tenant compte de l’Unicode, tandis que QRegularExpression nécessite une option distincte ; voir ci-dessous pour plus de détails.
• Dans QRegExp, « c{.} » correspond par défaut à tous les caractères, y compris le caractère de nouvelle ligne. QRegularExpression exclut par défaut le caractère de nouvelle ligne. Pour inclure le caractère de nouvelle ligne, définissez l’option de motif « QRegularExpression::DotMatchesEverythingOption ».

Pour un aperçu de la syntaxe des expressions régulières prise en charge par QRegularExpression, veuillez vous reporter à la page de manuel pcrepattern(3), qui décrit la syntaxe des motifs prise en charge par PCRE (l’implémentation de référence des expressions régulières compatibles Perl).

Portage depuis QRegExp::exactMatch()

QRegExp::exactMatch() remplissait deux fonctions : elle effectuait une correspondance exacte entre une expression régulière et une chaîne de caractères, et elle implémentait la correspondance partielle.

Portage de la correspondance exacte de QRegExp

La correspondance exacte indique si l'expression régulière correspond à l'intégralité de la chaîne de caractères. Par exemple, les classes renvoient les résultats suivants pour la chaîne « "abc123" » :

La correspondance exacte n'est pas prise en compte dans ` QRegularExpression`. Si vous souhaitez vous assurer que la chaîne de caractères correspond exactement à l'expression régulière, vous pouvez encapsuler le motif à l'aide de la fonction ` QRegularExpression::anchoredPattern()` :

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

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

Portage depuis la correspondance partielle de QRegExp

Lors de l'utilisation de QRegExp::exactMatch(), si aucune correspondance exacte n'a été trouvée, il est tout de même possible de déterminer la partie de la chaîne de caractères qui a été mise en correspondance avec l'expression régulière en appelant QRegExp::matchedLength(). Si la longueur renvoyée est égale à la longueur de la chaîne de caractères, on peut alors en conclure qu'une correspondance partielle a été trouvée.

QRegularExpression prend explicitement en charge la correspondance partielle grâce à la fonction appropriée QRegularExpression::MatchType.

Correspondance globale

En raison des limitations de l'API QRegExp, il n'a pas été possible d'implémenter correctement la correspondance globale (c'est-à-dire comme le fait Perl). En particulier, les motifs pouvant correspondre à 0 caractère (comme "a*") posent problème.

QRegularExpression::globalMatch() implémente correctement la correspondance globale de Perl, et l'itérateur renvoyé peut être utilisé pour examiner chaque résultat.

Par exemple, si vous avez un code tel que :

QString subject("the quick fox");

int offset = 0;
QRegExp re("(\\w+)");
while ((offset = re.indexIn(subject, offset)) != -1) {
    offset += re.matchedLength();
    // ...
}

Vous pouvez le réécrire ainsi :

QString subject("the quick fox");

QRegularExpression re("(\\w+)");
QRegularExpressionMatchIterator i = re.globalMatch(subject);
while (i.hasNext()) {
    QRegularExpressionMatch match = i.next();
    // ...
}

Prise en charge des propriétés Unicode

Lorsque vous utilisez QRegExp, les classes de caractères telles que \w, \d, etc. correspondent aux caractères possédant la propriété Unicode correspondante : par exemple, \d correspond à tout caractère possédant la propriété Unicode « Nd » (chiffre décimal).

Par défaut, ces classes de caractères ne correspondent qu’aux caractères ASCII lorsqu’on utilise QRegularExpression: par exemple, \d correspond exactement à un caractère de la plage ASCII 0-9. Il est possible de modifier ce comportement en utilisant l’option de motif QRegularExpression::UseUnicodePropertiesOption.

Correspondance avec des caractères génériques

Il n’existe pas de moyen direct d’effectuer une correspondance avec des caractères génériques dans QRegularExpression. Cependant, la méthode QRegularExpression::wildcardToRegularExpression() est fournie pour traduire les motifs glob en une expression régulière compatible avec Perl pouvant être utilisée à cette fin.

Par exemple, si vous avez un code tel que :

QRegExp wildcard("*.txt");
wildcard.setPatternSyntax(QRegExp::Wildcard);

Vous pouvez le réécrire ainsi :

auto wildcard = QRegularExpression(QRegularExpression::wildcardToRegularExpression("*.txt"));

Veuillez toutefois noter que certains motifs génériques de type « shell » peuvent ne pas être convertis comme vous vous y attendez. L'exemple de code suivant cessera de fonctionner sans avertissement s'il est simplement converti à l'aide de la fonction mentionnée ci-dessus :

const QString fp1("C:/Users/dummy/files/content.txt");
const QString fp2("/home/dummy/files/content.txt");

QRegExp re1("*/files/*");
re1.setPatternSyntax(QRegExp::Wildcard);
re1.exactMatch(fp1); // returns true
re1.exactMatch(fp2); // returns true

// but converted with QRegularExpression::wildcardToRegularExpression()

QRegularExpression re2(QRegularExpression::wildcardToRegularExpression("*/files/*"));
re2.match(fp1).hasMatch(); // returns false
re2.match(fp2).hasMatch(); // returns false

En effet, par défaut, l'expression régulière renvoyée par QRegularExpression::wildcardToRegularExpression() est entièrement ancrée. Pour obtenir une expression régulière non ancrée, transmettez QRegularExpression::UnanchoredWildcardConversion comme option de conversion :

QRegularExpression re3(QRegularExpression::wildcardToRegularExpression(
                           "*/files/*", QRegularExpression::UnanchoredWildcardConversion));
re3.match(fp1).hasMatch(); // returns true
re3.match(fp2).hasMatch(); // returns true

Correspondance minimale

QRegExp::setMinimal() implémentait la correspondance minimale en inversant simplement la « gloutonnerie » des quantificateurs (QRegExp ne prenait pas en charge les quantificateurs paresseux, tels que *?, +?, etc.). QRegularExpression prend en revanche en charge les quantificateurs gloutons, paresseux et possessifs. L’option de motif « QRegularExpression::InvertedGreedinessOption » peut être utile pour émuler les effets de ` QRegExp::setMinimal()` : si elle est activée, elle inverse le comportement des quantificateurs (les quantificateurs gourmands deviennent paresseux et vice versa).

Modes Caret

L’option de correspondance « QRegularExpression::AnchorAtOffsetMatchOption » peut être utilisée pour émuler le comportement de « QRegExp::CaretAtOffset ». Il n’existe pas d’équivalent pour les autres modes de « QRegExp::CaretMode ».