QRegularExpression Class

Description détaillée

Les expressions régulières, ou regexps, constituent un outil très puissant pour traiter les chaînes de caractères et les textes. Elles s'avèrent utiles dans de nombreux contextes, par exemple :

Ce document ne constitue en aucun cas une référence exhaustive sur la correspondance de motifs à l'aide d'expressions régulières, et les parties suivantes nécessiteront que le lecteur dispose de connaissances de base sur les expressions régulières de type Perl et leur syntaxe de motifs.

Voici quelques bonnes références sur les expressions régulières :

• Mastering Regular Expressions (troisième édition) de Jeffrey E. F. Friedl, ISBN 0-596-52812-4 ;
• 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 avec Perl) ;
• la documentation sur les expressions régulières de Perl et le tutoriel sur les expressions régulières de Perl.

Introduction

QRegularExpression implémente les expressions régulières compatibles avec Perl. Il prend entièrement en charge Unicode. 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) mentionnée ci-dessus. Une expression régulière se compose de deux éléments : une chaîne de motif et un ensemble d'options de motif qui modifient la signification de la chaîne de motif.

Vous pouvez définir la chaîne de motif en transmettant une chaîne au constructeur de QRegularExpression :

QRegularExpression re("a pattern");

Cela définit la chaîne de motif sur a pattern. Vous pouvez également utiliser la fonction setPattern() pour définir un motif sur un objet QRegularExpression existant :

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

Notez qu’en raison des règles relatives aux chaînes littérales en C++, vous devez échapper toutes les barres obliques inversées présentes dans la chaîne de motif à l’aide d’une autre barre oblique inversée :

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

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

Vous pouvez également utiliser une chaîne littérale brute; dans ce cas, vous n’avez pas besoin d’échapper les barres obliques inversées dans le motif, car tous les caractères situés entre R"(...)" sont considérés comme des caractères bruts. Comme vous pouvez le voir dans l’exemple suivant, cela simplifie l’écriture des motifs :

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

La fonction pattern() renvoie le motif actuellement défini pour un objet QRegularExpression :

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

Options de motif

La signification de la chaîne de motif peut être modifiée en définissant une ou plusieurs options de motif. Par exemple, il est possible de configurer un motif pour qu’il effectue une correspondance sans distinction de casse en définissant l’option ` QRegularExpression::CaseInsensitiveOption`.

Vous pouvez définir ces options en les transmettant au constructeur de QRegularExpression, comme suit :

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

Vous pouvez également utiliser la fonction ` setPatternOptions()` sur un objet `QRegularExpressionObject` existant :

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

Il est possible de récupérer les options de motif actuellement définies sur un objet QRegularExpression à l'aide de la fonction patternOptions() :

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

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

Veuillez vous reporter à la documentation relative à l'énumération QRegularExpression::PatternOption pour plus d'informations sur chaque option de motif.

Type de correspondance et options de correspondance

Les deux derniers arguments des fonctions match() et globalMatch() permettent de définir le type de correspondance et les options de correspondance. Le type de correspondance est une valeur de l'énumération QRegularExpression::MatchType; l'algorithme de correspondance « traditionnel » est sélectionné en utilisant le type de correspondance NormalMatch (valeur par défaut). Il est également possible d'activer la correspondance partielle de l'expression régulière par rapport à une chaîne de caractères : consultez la section partial matching pour plus de détails.

Les options de correspondance constituent un ensemble d’une ou plusieurs valeurs de l’énumération QRegularExpression::MatchOption. Elles modifient la manière dont s’effectue une correspondance spécifique entre une expression régulière et une chaîne de caractères. Veuillez vous reporter à la documentation de l’énumération QRegularExpression::MatchOption pour plus de détails.

Correspondance normale

Pour effectuer une correspondance, il suffit d’appeler la fonction ` match()` en lui passant une chaîne à comparer. Cette chaîne est appelée « chaîne sujet ». La fonction ` match()` renvoie un objet ` QRegularExpressionMatch ` qui permet d’examiner les résultats de la correspondance. Par exemple :

// 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 recherche aboutit, le groupe de capture (implicite) numéro 0 peut être utilisé pour récupérer la sous-chaîne correspondant à l’ensemble du motif (voir également la section consacrée à 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"
    // ...
}

Il est également possible de démarrer une recherche à un décalage arbitraire à l’intérieur de la chaîne de caractères en passant ce décalage en argument de la fonction ` match()`. Dans l’exemple suivant, ` "12 abc" ` n’est pas trouvé car la recherche commence au décalage 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"
    // ...
}

Extraction des sous-chaînes capturées

L’objet ` QRegularExpressionMatch ` contient également des informations sur les sous-chaînes capturées par les groupes de capture dans la chaîne de motif. La fonction ` captured()` renvoie la chaîne capturée par le n-ième groupe de capture :

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

Les groupes de capture du motif sont numérotés à partir de 1, et le groupe de capture implicite 0 sert à capturer la sous-chaîne qui correspond à l'intégralité du motif.

Il est également possible de récupérer les indices de début et de fin (dans la chaîne sujet) de chaque sous-chaîne capturée, à l'aide des fonctions ` capturedStart()` et ` 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
    // ...
}

Toutes ces fonctions disposent d’une surcharge prenant un ` QString ` en paramètre afin d’extraire des sous-chaînes capturées nommées. Par exemple :

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
}

Correspondance globale

La correspondance globale est utile pour trouver toutes les occurrences d’une expression régulière donnée à l’intérieur d’une chaîne de caractères. Supposons que l’on souhaite extraire tous les mots d’une chaîne donnée, un mot étant une sous-chaîne correspondant au motif \w+.

QRegularExpression::globalMatch renvoie un objet de type ` QRegularExpressionMatchIterator`, qui est un itérateur avant de type Java pouvant être utilisé pour parcourir les résultats. Par exemple :

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

Comme il s'agit d'un itérateur de type Java, l'QRegularExpressionMatchIterator pointera immédiatement avant le premier résultat. Chaque résultat est renvoyé sous la forme d'un objet ` QRegularExpressionMatch `. La fonction ` hasNext()` renverra `true` s'il reste au moins un résultat, et ` next()` renverra le résultat suivant et fera avancer l'itérateur. Pour reprendre l'exemple précédent :

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

Vous pouvez également utiliser ` peekNext()` pour obtenir le résultat suivant sans faire avancer l’itérateur.

Il est également possible d’utiliser simplement le résultat de ` QRegularExpression::globalMatch ` dans une boucle `for` basée sur une plage, par exemple comme ceci :

// 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)) {
    // ...
}

Il est possible de passer un décalage de départ et une ou plusieurs options de correspondance à la fonction globalMatch(), exactement comme pour une correspondance normale avec match().

Correspondance partielle

On obtient une correspondance partielle lorsque la fin de la chaîne sujet est atteinte, mais qu'il manque encore des caractères pour que la correspondance soit complète. Notez qu'une correspondance partielle est généralement beaucoup moins efficace qu'une correspondance normale, car de nombreuses optimisations de l'algorithme de correspondance ne peuvent pas être utilisées.

Une correspondance partielle doit être explicitement demandée en spécifiant un type de correspondance « PartialPreferCompleteMatch » ou « PartialPreferFirstMatch » lors de l’appel de « QRegularExpression::match » ou « QRegularExpression::globalMatch ». Si une correspondance partielle est trouvée, l’appel de la fonction « hasMatch() » sur l’objet « QRegularExpressionMatch » renvoyé par « match() » renverra « false », mais « hasPartialMatch() » renverra « true ».

Lorsqu’une correspondance partielle est trouvée, aucune sous-chaîne capturée n’est renvoyée, et le groupe de capture (implicite) 0, correspondant à la correspondance complète, capture la sous-chaîne partiellement correspondante de la chaîne sujet.

Notez que la recherche d’une correspondance partielle peut tout de même aboutir à une correspondance complète, si celle-ci est trouvée ; dans ce cas, ` hasMatch()` renverra ` true ` et ` hasPartialMatch()` renverra ` false`. Il n’arrive jamais qu’une fonction ` QRegularExpressionMatch ` signale à la fois une correspondance partielle et une correspondance complète.

La correspondance partielle est principalement utile dans deux cas de figure : la validation en temps réel des saisies utilisateur et la correspondance incrémentielle ou multisegment.

Validation des données saisies par l’utilisateur

Supposons que nous souhaitions que l'utilisateur saisisse une date dans un format spécifique, par exemple « MMM jj, aaaa ». Nous pouvons vérifier la validité de la saisie à l'aide d'un modèle tel que :

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

(Ce modèle ne détecte pas les jours non valides, mais conservons-le pour les besoins de l'exemple).

Nous souhaitons valider la saisie à l'aide de cette expression régulière au fur et à mesure que l'utilisateur la saisit, afin de pouvoir signaler une erreur dès qu'elle se produit (par exemple, si l'utilisateur appuie sur la mauvaise touche). Pour ce faire, nous devons distinguer trois cas :

• la saisie ne peut en aucun cas correspondre à l'expression régulière ;
• la saisie correspond à l'expression régulière ;
• la saisie ne correspond pas à l'expression régulière pour le moment, mais elle y correspondra si d'autres caractères y sont ajoutés.

Notez que ces trois cas représentent exactement les états possibles d'un « QValidator » (voir l'énumération « QValidator::State »).

En particulier, dans le dernier cas, nous souhaitons que le moteur d’expressions régulières signale une correspondance partielle : nous parvenons à faire correspondre le motif à la chaîne sujet, mais la correspondance ne peut se poursuivre car la fin de la chaîne sujet a été atteinte. Notez toutefois que l’algorithme de correspondance doit se poursuivre et tester toutes les possibilités ; si une correspondance complète (et non partielle) est trouvée, celle-ci doit alors être signalée, et la chaîne d’entrée acceptée comme entièrement valide.

Ce comportement est implémenté par le type de correspondance « PartialPreferCompleteMatch ». Par exemple :

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 l’application de la même expression régulière à la chaîne sujet aboutit à une correspondance complète, celle-ci est signalée comme d’habitude :

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

Voici un autre exemple avec un motif différent, illustrant le comportement consistant à privilégier une correspondance complète plutôt qu'une correspondance partielle :

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"

Dans ce cas, le sous-motif abc\\w+X correspond partiellement à la chaîne de caractères ; cependant, le sous-motif def correspond entièrement à la chaîne de caractères, et c'est donc une correspondance complète qui est signalée.

Si plusieurs correspondances partielles sont trouvées lors de la recherche (mais aucune correspondance complète), l'objet QRegularExpressionMatch signalera la première trouvée. Par exemple :

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"

Correspondance incrémentielle/multisegment

La recherche incrémentielle est un autre cas d’utilisation de la correspondance partielle. Supposons que l’on souhaite trouver les occurrences d’une expression régulière au sein d’un texte volumineux (c’est-à-dire les sous-chaînes correspondant à l’expression régulière). Pour ce faire, on souhaite « alimenter » les moteurs d’expressions régulières avec ce texte volumineux par petits morceaux. Le problème évident est de savoir ce qui se passe si la sous-chaîne qui correspond à l’expression régulière s’étend sur deux segments ou plus.

Dans ce cas, le moteur d'expressions régulières doit signaler une correspondance partielle, afin que nous puissions effectuer une nouvelle recherche en ajoutant de nouvelles données et (à terme) obtenir une correspondance complète. Cela implique que le moteur d’expressions régulières peut supposer qu’il existe d’autres caractères au-delà de la fin de la chaîne de recherche. Il ne faut pas prendre cela au pied de la lettre : le moteur n’essaiera jamais d’accéder à un caractère situé après le dernier de la chaîne de recherche.

QRegularExpression met en œuvre ce comportement lorsqu’on utilise le type de correspondance « PartialPreferFirstMatch ». Ce type de correspondance signale une correspondance partielle dès qu’elle est trouvée, et les autres alternatives de correspondance ne sont pas testées (même si elles pourraient aboutir à une correspondance complète). Par exemple :

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

Cela s'explique par le fait que, lors de la recherche de la première branche de l'opérateur d'alternative, une correspondance partielle est trouvée, ce qui met fin à la recherche sans que la deuxième branche ne soit testée. Autre exemple :

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

Cela illustre ce qui peut sembler être un comportement contre-intuitif des quantificateurs : comme la règle « ? » est gloutonne, le moteur tente d’abord de poursuivre la correspondance après avoir trouvé une correspondance avec « "abc" » ; mais la correspondance atteint alors la fin de la chaîne sujet, et une correspondance partielle est donc signalée. Cela est encore plus surprenant dans l’exemple suivant :

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

Il est facile de comprendre ce comportement si l’on se souvient que le moteur s’attend à ce que la chaîne sujet ne soit qu’une sous-chaîne du texte complet dans lequel on recherche une correspondance (c’est-à-dire, comme nous l’avons dit précédemment, que le moteur suppose qu’il y a d’autres caractères au-delà de la fin de la chaîne sujet).

Comme le quantificateur « * » est glouton, signaler une correspondance complète pourrait constituer une erreur, car après l’ "abc" e sujet actuelle, il pourrait y avoir d’autres occurrences de « "abc" ». Par exemple, le texte complet aurait pu être « abcabcX », et la correspondance correcte à signaler (dans le texte complet) aurait donc été « "abcabc" » ; en ne faisant correspondre que la partie initiale « "abc" », on obtient au contraire une correspondance partielle.

Gestion des erreurs

Il est possible qu’un objet `QRegularExpression` soit invalide en raison d’erreurs de syntaxe dans la chaîne de motif. La fonction ` isValid()` renvoie `true` si l’expression régulière est valide, ou `false` dans le cas contraire :

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

Vous pouvez obtenir plus d’informations sur l’erreur spécifique en appelant la fonction ` errorString()` ; de plus, la fonction ` patternErrorOffset()` renverra l’offset à l’intérieur de la chaîne de motif

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

Si une correspondance est tentée avec une expression QRegularExpression non valide, l’objet QRegularExpressionMatch renvoyé sera également invalide (c’est-à-dire que sa fonction isValid() renverra false). Il en va de même pour les tentatives de correspondance globale.

Fonctionnalités des expressions régulières compatibles Perl non prises en charge

QRegularExpression ne prend pas en charge toutes les fonctionnalités disponibles dans les expressions régulières compatibles Perl. La plus notable est le fait que les noms dupliqués pour les groupes de capture ne sont pas pris en charge, et leur utilisation peut entraîner un comportement indéfini.

Cela pourrait changer dans une future version de Qt.

Débogage du code utilisant QRegularExpression

QRegularExpression utilise en interne un compilateur « just-in-time » (JIT) pour optimiser l’exécution de l’algorithme de correspondance. Le JIT recourt largement au code auto-modifiable, ce qui peut entraîner le plantage d’outils de débogage tels que Valgrind. Vous devez activer toutes les vérifications relatives au code auto-modifiable si vous souhaitez déboguer des programmes utilisant QRegularExpression (par exemple, l'option de ligne de commande « --smc-check » de Valgrind). L'inconvénient de l'activation de ces vérifications est que votre programme s'exécutera de manière nettement plus lente.

Pour éviter cela, le JIT est désactivé par défaut si vous compilez Qt en mode débogage. Il est possible de passer outre ce comportement par défaut et d’activer ou de désactiver l’utilisation du JIT (aussi bien en mode débogage qu’en mode production) en définissant la variable d’environnement ` QT_ENABLE_REGEXP_JIT ` respectivement sur une valeur non nulle ou nulle.