QRegularExpression Class

Description détaillée

Les expressions régulières, ou regexps, sont un outil très puissant pour manipuler des chaînes de caractères et des textes. Cela est utile dans de nombreux contextes, par exemple,

Ce document n'est en aucun cas une référence complète sur la recherche de motifs à l'aide d'expressions régulières, et les parties suivantes nécessiteront de la part du lecteur des connaissances de base sur les expressions régulières de type Perl et leur syntaxe de motifs.

Parmi les bonnes références sur les expressions régulières, on peut citer

• Mastering Regular Expressions (troisième édition) par 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 supporte entièrement l'Unicode. Pour une vue d'ensemble de la syntaxe des expressions régulières supportée par QRegularExpression, veuillez vous référer à la page de manuel pcrepattern(3) mentionnée plus haut. Une expression régulière se compose de deux éléments : une chaîne de motifs et un ensemble d'options de motifs qui modifient la signification de la chaîne de motifs.

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

QRegularExpression re("a pattern");

Ceci définit la chaîne de motifs à 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 du C++, vous devez échapper à toutes les barres obliques inverses à l'intérieur de la chaîne de motifs par 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, auquel cas vous n'avez pas besoin d'échapper aux barres obliques inverses dans le motif, tous les caractères entre R"(...)" étant 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 motifs peut être modifiée en définissant une ou plusieurs options de motifs. Par exemple, il est possible de configurer un motif pour qu'il corresponde insensiblement à la casse en définissant l'option QRegularExpression::CaseInsensitiveOption.

Vous pouvez définir les options en les passant au constructeur de QRegularExpression, comme dans l'exemple suivant :

// 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 d'obtenir les options de motif actuellement définies sur un objet QRegularExpression en utilisant la fonction patternOptions() :

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

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

Veuillez vous référer à la documentation de l'enum 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() définissent 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 choisi en utilisant le type de correspondance NormalMatch (par défaut). Il est également possible d'activer une correspondance partielle de l'expression régulière par rapport à une chaîne de caractères : voir la section partial matching pour plus de détails.

Les options de correspondance sont un ensemble d'une ou plusieurs valeurs QRegularExpression::MatchOption. Elles modifient la manière dont une expression régulière est comparée à une chaîne de caractères. Veuillez consulter la documentation de l'énumération QRegularExpression::MatchOption pour plus de détails.

Correspondance normale

Pour effectuer une correspondance, il suffit d'invoquer la fonction match() en lui transmettant une chaîne de caractères à comparer. Nous appelons cette chaîne la chaîne du sujet. Le résultat de la fonction match() est un objet QRegularExpressionMatch qui peut être utilisé pour inspecter 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 correspondance est réussie, le numéro de groupe de capture (implicite) 0 peut être utilisé pour récupérer la sous-chaîne correspondant à l'ensemble du motif (voir également la section concernant 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 commencer une recherche à un emplacement arbitraire dans la chaîne du sujet en passant l'emplacement en tant qu'argument de la fonction match(). Dans l'exemple suivant, "12 abc" n'est pas pris en compte parce que la correspondance est lancée à l'offset 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 motifs. 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 dans le motif sont numérotés à partir de 1, et le groupe de capture implicite 0 est utilisé pour capturer la sous-chaîne qui correspond à l'ensemble du motif.

Il est également possible de récupérer les décalages de début et de fin (à l'intérieur de la chaîne du sujet) de chaque sous-chaîne capturée, en utilisant les 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 ont une surcharge prenant un QString comme paramètre afin d'extraire les 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

Lacorrespondance 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 nous voulions extraire tous les mots d'une chaîne donnée, où un mot est une sous-catégorie correspondant au modèle \w+.

QRegularExpression::globalMatch renvoie un QRegularExpressionMatchIterator, qui est un itérateur de type Java qui peut être utilisé pour itérer sur 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'adresse QRegularExpressionMatchIterator pointera immédiatement avant le premier résultat. Chaque résultat est renvoyé sous la forme d'un objet QRegularExpressionMatch. La fonction hasNext() renvoie un vrai résultat s'il y en a au moins un de plus, et next() renvoie le résultat suivant et fait avancer l'itérateur. Reprenons 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 l'intervalle, 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 une correspondance normale avec match().

Correspondance partielle

Une correspondance partielle est obtenue lorsque la fin de la chaîne de caractères du sujet est atteinte, mais que d'autres caractères sont nécessaires pour compléter la correspondance. Notez qu'une correspondance partielle est généralement beaucoup plus inefficace 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 de PartialPreferCompleteMatch ou PartialPreferFirstMatch lors de l'appel à QRegularExpression::match ou QRegularExpression::globalMatch. Si une correspondance partielle est trouvée, l'appel à 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 0 (implicite) correspondant à la correspondance complète capture la sous-chaîne partiellement correspondante de la chaîne de l'objet.

Notez que le fait de demander une correspondance partielle peut toujours conduire à une correspondance complète, si elle est trouvée ; dans ce cas, hasMatch() renverra true et hasPartialMatch() false. Il n'arrive jamais qu'un site QRegularExpressionMatch signale à la fois une correspondance partielle et une correspondance complète.

La correspondance partielle est principalement utile dans deux scénarios : la validation de l'entrée de l'utilisateur en temps réel et la correspondance incrémentale/multi-segments.

Validation de l'entrée 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 l'entrée à 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 motif ne prend pas en compte les jours invalides, mais gardons-le pour les besoins de l'exemple).

Nous aimerions valider l'entrée avec cette expression régulière pendant que l'utilisateur la tape, afin de pouvoir signaler une erreur dans l'entrée dès qu'elle est commise (par exemple, l'utilisateur a tapé la mauvaise touche). Pour ce faire, nous devons distinguer trois cas :

• l'entrée ne peut pas correspondre à l'expression régulière ;
• l'entrée correspond à l'expression régulière ;
• l'entrée ne correspond pas à l'expression régulière pour l'instant, 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 site QValidator (voir l'énumération QValidator::State ).

En particulier, dans le dernier cas, nous voulons que le moteur d'expressions régulières signale une correspondance partielle : nous parvenons à faire correspondre le motif à la chaîne du sujet, mais la correspondance ne peut pas se poursuivre parce que la fin du sujet est rencontrée. Notez cependant que l'algorithme de correspondance doit continuer et essayer toutes les possibilités, et dans le cas où une correspondance complète (non partielle) est trouvée, celle-ci doit être signalée, et la chaîne d'entrée doit être acceptée comme entièrement valide.

Ce comportement est mis en œuvre 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 la correspondance entre la même expression régulière et la chaîne du sujet aboutit à une correspondance complète, elle 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

Un autre exemple avec un motif différent, montrant le comportement qui consiste à préférer une correspondance complète à 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 du sujet ; cependant, le sous-motif def correspond complètement à la chaîne du sujet, et une correspondance complète est donc signalée.

Si plusieurs correspondances partielles sont trouvées lors de la recherche (mais pas de 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émentale/multi-segments

La correspondance incrémentielle est un autre cas d'utilisation de la correspondance partielle. Supposons que nous voulions trouver les occurrences d'une expression régulière dans un texte volumineux (c'est-à-dire les sous-chaînes correspondant à l'expression régulière). Pour ce faire, nous aimerions "alimenter" les moteurs d'expressions régulières en 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 ou plusieurs morceaux.

Dans ce cas, le moteur d'expressions régulières doit signaler une correspondance partielle, de sorte que nous puissions procéder à une nouvelle correspondance en ajoutant de nouvelles données et obtenir (éventuellement) une correspondance complète. Cela implique que le moteur d'expressions régulières peut supposer qu'il y a d'autres caractères au-delà de la fin de la chaîne du sujet. Cela ne doit pas être pris au pied de la lettre : le moteur n'essaiera jamais d'accéder à un caractère après le dernier du sujet.

QRegularExpression met en œuvre ce comportement lors de l'utilisation du 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 essayées (même si elles pourraient conduire à 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 se produit parce qu'en faisant correspondre la première branche de l'opérateur d'alternance, une correspondance partielle est trouvée, et donc la correspondance s'arrête, sans essayer la deuxième branche. Autre exemple :

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

Ceci montre ce qui pourrait sembler être un comportement contre-intuitif des quantificateurs : puisque ? est gourmand, le moteur essaie d'abord de poursuivre la recherche après avoir trouvé "abc"; mais la recherche atteint alors la fin de la chaîne du sujet, et une recherche partielle est donc signalée. Ce comportement 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 nous nous rappelons que le moteur s'attend à ce que la chaîne du sujet ne soit qu'une sous-chaîne du texte entier dans lequel nous cherchons 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 du sujet).

Comme le quantificateur * est gourmand, signaler une correspondance complète pourrait être une erreur, car après le sujet actuel "abc", il peut y avoir d'autres occurrences de "abc". Par exemple, le texte complet aurait pu être "abcabcX", et donc la bonne correspondance à signaler (dans le texte complet) aurait été "abcabc"; en ne correspondant qu'au "abc" de tête, nous obtenons 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 caractères. La fonction isValid() renvoie un message vrai si l'expression régulière est valide, ou faux 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() ; en outre, la fonction patternErrorOffset() renverra le décalage dans la chaîne de caractères.

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 QRegularExpression invalide, 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 non prises en charge des expressions régulières compatibles avec Perl

QRegularExpression ne prend pas en charge toutes les fonctionnalités disponibles dans les expressions régulières compatibles avec 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 conduire à un comportement indéfini.

Cela pourrait changer dans une future version de Qt.

Débogage du code qui utilise QRegularExpression

QRegularExpression utilise en interne un compilateur juste à temps (JIT) pour optimiser l'exécution de l'algorithme de correspondance. Le JIT fait un usage intensif du code auto-modifiant, ce qui peut faire planter des outils de débogage tels que Valgrind. Vous devez activer toutes les vérifications du code auto-modifiant si vous voulez 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 contrôles est que votre programme s'exécutera beaucoup plus lentement.

Pour éviter cela, le JIT est désactivé par défaut si vous compilez Qt en mode débogage. Il est possible d'outrepasser la valeur par défaut et d'activer ou de désactiver l'utilisation de l'ITC (à la fois en mode debug ou release) en définissant la variable d'environnement QT_ENABLE_REGEXP_JIT à une valeur non nulle ou nulle respectivement.