QRegularExpression Class

Ausführliche Beschreibung

Reguläre Ausdrücke, auch Regexps genannt, sind ein sehr leistungsfähiges Werkzeug zur Verarbeitung von Zeichenketten und Texten. Dies ist in vielen Zusammenhängen nützlich, z. B.

Dieses Dokument ist keineswegs eine vollständige Referenz zum Musterabgleich mit regulären Ausdrücken, und die folgenden Abschnitte setzen beim Leser gewisse Grundkenntnisse über Perl-ähnliche reguläre Ausdrücke und deren Mustersyntax voraus.

Zu den empfehlenswerten Nachschlagewerken zum Thema reguläre Ausdrücke gehören:

• „Mastering Regular Expressions“ (3. Auflage) von Jeffrey E. F. Friedl, ISBN 0-596-52812-4;
• die Manpage pcrepattern(3), die die von PCRE (der Referenzimplementierung Perl-kompatibler regulärer Ausdrücke) unterstützte Mustersyntax beschreibt;
• die Dokumentation zu regulären Ausdrücken in Perl sowie das Tutorial zu regulären Ausdrücken in Perl.

Einleitung

QRegularExpression implementiert Perl-kompatible reguläre Ausdrücke. Es unterstützt Unicode vollständig. Einen Überblick über die von QRegularExpression unterstützte Syntax regulärer Ausdrücke finden Sie in der oben genannten Manpage pcrepattern(3). Ein regulärer Ausdruck besteht aus zwei Teilen: einer Musterzeichenfolge und einer Reihe von Musteroptionen, die die Bedeutung der Musterzeichenfolge verändern.

Sie können die Musterzeichenfolge festlegen, indem Sie dem Konstruktor von QRegularExpression eine Zeichenkette übergeben:

QRegularExpression re("a pattern");

Dadurch wird die Musterzeichenfolge auf „ a pattern “ gesetzt. Sie können auch die Funktion ` setPattern()` verwenden, um ein Muster für ein vorhandenes `QRegularExpression`-Objekt festzulegen:

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

Beachten Sie, dass Sie aufgrund der Regeln für C++-Literalzeichenfolgen alle Backslashes innerhalb der Musterzeichenfolge mit einem weiteren Backslash escapen müssen:

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

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

Alternativ können Sie ein Raw-String-Literal verwenden. In diesem Fall müssen Sie Backslashes im Muster nicht mit einem Backslash maskieren, da alle Zeichen zwischen R"(...)" als Raw-Zeichen behandelt werden. Wie Sie im folgenden Beispiel sehen können, vereinfacht dies das Schreiben von Mustern:

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

Die Funktion ` pattern()` gibt das Muster zurück, das derzeit für ein `QRegularExpression`-Objekt festgelegt ist:

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

Musteroptionen

Die Bedeutung der Musterzeichenfolge kann durch das Festlegen einer oder mehrerer Musteroptionen geändert werden. So ist es beispielsweise möglich, ein Muster so einzustellen, dass es groß- und kleinschreibungsunabhängig passt, indem die Option ` QRegularExpression::CaseInsensitiveOption` gesetzt wird.

Sie können die Optionen festlegen, indem Sie sie an den Konstruktor von `QRegularExpression` übergeben, wie im folgenden Beispiel:

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

Alternativ können Sie die Funktion ` setPatternOptions()` auf ein vorhandenes `QRegularExpressionObject` anwenden:

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

Mit der Funktion ` patternOptions()` lassen sich die aktuell für ein `QRegularExpression`-Objekt festgelegten Musteroptionen abrufen:

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

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

Weitere Informationen zu den einzelnen Musteroptionen finden Sie in der Dokumentation zur enum „ QRegularExpression::PatternOption “.

Übereinstimmungstyp und Übereinstimmungsoptionen

Die letzten beiden Argumente der Funktionen ` match()` und ` globalMatch()` legen den Abgleichtyp und die Abgleichoptionen fest. Der Abgleichtyp ist ein Wert der Enumeration „ QRegularExpression::MatchType “; der „traditionelle“ Abgleichalgorithmus wird durch Verwendung des Abgleichtyps „ NormalMatch “ (Standard) ausgewählt. Es ist auch möglich, einen partiellen Abgleich des regulären Ausdrucks mit einer Zielzeichenfolge zu aktivieren: Weitere Details finden Sie im Abschnitt „ partial matching “.

Die Übereinstimmungsoptionen bestehen aus einer oder mehreren Werten der Enumeration „ QRegularExpression::MatchOption “. Sie beeinflussen die Art und Weise, wie eine bestimmte Übereinstimmung eines regulären Ausdrucks mit einer Zielzeichenfolge durchgeführt wird. Weitere Details finden Sie in der Dokumentation zur Enumeration „ QRegularExpression::MatchOption “.

Normales Abgleichen

Um einen Abgleich durchzuführen, können Sie einfach die Funktion ` match()` aufrufen und dabei eine Zeichenkette übergeben, gegen die abgeglichen werden soll. Diese Zeichenkette bezeichnen wir als Zielzeichenkette. Das Ergebnis der Funktion ` match()` ist ein ` QRegularExpressionMatch `-Objekt, mit dem Sie die Ergebnisse des Abgleichs überprüfen können. Zum Beispiel:

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

Ist der Abgleich erfolgreich, kann die (implizite) Erfassungsgruppe Nummer 0 verwendet werden, um die Teilzeichenfolge abzurufen, die mit dem gesamten Muster übereinstimmt (siehe auch den Abschnitt über ` 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"
    // ...
}

Es ist auch möglich, einen Abgleich an einer beliebigen Stelle innerhalb der Suchzeichenfolge zu beginnen, indem der Offset als Argument der Funktion ` match()` übergeben wird. Im folgenden Beispiel wird „ "12 abc" “ nicht gefunden, da der Abgleich ab Offset 1 beginnt:

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

Extrahieren von erfassten Teilzeichenfolgen

Das ` QRegularExpressionMatch `-Objekt enthält außerdem Informationen zu den Teilzeichenfolgen, die von den Erfassungsgruppen im Musterzeichenfolgen-String erfasst wurden. Die Funktion ` captured()` gibt die von der n-ten Erfassungsgruppe erfasste Zeichenfolge zurück:

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

Erfassungsgruppen im Muster werden beginnend mit 1 nummeriert, und die implizite Erfassungsgruppe 0 wird verwendet, um die Teilzeichenfolge zu erfassen, die mit dem gesamten Muster übereinstimmt.

Es ist außerdem möglich, den Start- und End-Offset (innerhalb der Zielzeichenfolge) jeder erfassten Teilzeichenfolge mithilfe der Funktionen ` capturedStart()` und ` capturedEnd()` abzurufen:

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

Alle diese Funktionen verfügen über eine Überladung, die einen „ QString “ als Parameter akzeptiert, um benannte erfasste Teilzeichenfolgen zu extrahieren. Zum Beispiel:

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
}

Globales Abgleichen

Der globale Abgleich ist nützlich, um alle Vorkommen eines bestimmten regulären Ausdrucks innerhalb einer Zielzeichenfolge zu finden. Angenommen, wir möchten alle Wörter aus einer gegebenen Zeichenfolge extrahieren, wobei ein Wort eine Teilzeichenfolge ist, die dem Muster \w+ entspricht.

QRegularExpression::globalMatch gibt ein ` QRegularExpressionMatchIterator` zurück, bei dem es sich um einen Java-ähnlichen Vorwärtsiterator handelt, mit dem die Ergebnisse durchlaufen werden können. Zum Beispiel:

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

Da es sich um einen Java-ähnlichen Iterator handelt, zeigt der „ QRegularExpressionMatchIterator “ unmittelbar vor dem ersten Ergebnis. Jedes Ergebnis wird als „ QRegularExpressionMatch “-Objekt zurückgegeben. Die Funktion „ hasNext()“ gibt „true“ zurück, wenn mindestens ein weiteres Ergebnis vorhanden ist, und „ next()“ gibt das nächste Ergebnis zurück und verschiebt den Iterator um einen Schritt weiter. Anknüpfend an das vorherige Beispiel:

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

Sie können auch ` peekNext()` verwenden, um das nächste Ergebnis abzurufen, ohne den Iterator weiterzuschreiten.

Es ist auch möglich, das Ergebnis von ` QRegularExpression::globalMatch ` einfach in einer bereichsbasierten `for`-Schleife zu verwenden, beispielsweise wie folgt:

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

Es ist möglich, einen Start-Offset und eine oder mehrere Übereinstimmungsoptionen an die Funktion ` globalMatch()` zu übergeben, genau wie beim normalen Abgleich mit ` match()`.

Teilweise Übereinstimmung

Ein Teilabgleich liegt vor, wenn das Ende der Suchzeichenfolge erreicht ist, aber noch weitere Zeichen benötigt werden, um den Abgleich erfolgreich abzuschließen. Beachten Sie, dass ein Teilabgleich in der Regel wesentlich ineffizienter ist als ein normaler Abgleich, da viele Optimierungen des Abgleichalgorithmus nicht angewendet werden können.

Ein Teilabgleich muss explizit angefordert werden, indem beim Aufruf von ` QRegularExpression::match ` oder ` QRegularExpression::globalMatch` der Abgleichstyp ` PartialPreferCompleteMatch ` oder ` PartialPreferFirstMatch ` angegeben wird. Wird ein Teilabgleich gefunden, gibt der Aufruf der Funktion ` hasMatch()` auf das von ` match()` zurückgegebene ` QRegularExpressionMatch `-Objekt ` false` zurück, während ` hasPartialMatch()` ` true` zurückgibt.

Wird eine teilweise Übereinstimmung gefunden, werden keine erfassten Teilzeichenfolgen zurückgegeben, und die (implizite) Erfassungsgruppe 0, die der gesamten Übereinstimmung entspricht, erfasst die teilweise übereinstimmende Teilzeichenfolge der Zielzeichenfolge.

Beachten Sie, dass die Abfrage nach einer Teilübereinstimmung dennoch zu einer vollständigen Übereinstimmung führen kann, sofern eine solche gefunden wird; in diesem Fall gibt „ hasMatch()“ „ true “ und „ hasPartialMatch()“ „ false “ zurück. Es kommt niemals vor, dass „ QRegularExpressionMatch “ sowohl eine Teil- als auch eine vollständige Übereinstimmung meldet.

Der Teilabgleich ist vor allem in zwei Szenarien nützlich: bei der Echtzeit-Validierung von Benutzereingaben und beim inkrementellen/mehrsegmentigen Abgleich.

Validierung von Benutzereingaben

Angenommen, wir möchten, dass der Benutzer ein Datum in einem bestimmten Format eingibt, zum Beispiel „MMM dd, yyyy“. Wir können die Gültigkeit der Eingabe mit einem Muster wie dem folgenden überprüfen:

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

(Dieses Muster erkennt zwar keine ungültigen Tage, aber behalten wir es für die Zwecke dieses Beispiels bei).

Wir möchten die Eingabe mit diesem regulären Ausdruck validieren, während der Benutzer sie eingibt, damit wir einen Fehler in der Eingabe melden können, sobald diese bestätigt wird (beispielsweise wenn der Benutzer eine falsche Taste gedrückt hat). Dazu müssen wir drei Fälle unterscheiden:

• Die Eingabe kann unmöglich mit dem regulären Ausdruck übereinstimmen;
• die Eingabe stimmt mit dem regulären Ausdruck überein;
• die Eingabe stimmt derzeit nicht mit dem regulären Ausdruck überein, wird dies aber tun, wenn weitere Zeichen hinzugefügt werden.

Beachten Sie, dass diese drei Fälle genau die möglichen Zustände eines „ QValidator “ darstellen (siehe die Enumeration „ QValidator::State “).

Insbesondere im letzten Fall soll die Engine für reguläre Ausdrücke eine teilweise Übereinstimmung melden: Wir gleichen das Muster erfolgreich mit der Zielzeichenkette ab, doch der Abgleich kann nicht fortgesetzt werden, da das Ende der Zielzeichenkette erreicht wurde. Beachten Sie jedoch, dass der Abgleichalgorithmus fortfahren und alle Möglichkeiten prüfen sollte; falls eine vollständige (nicht partielle) Übereinstimmung gefunden wird, sollte diese gemeldet und die Eingabezeichenfolge als vollständig gültig akzeptiert werden.

Dieses Verhalten wird durch den Übereinstimmungstyp „ PartialPreferCompleteMatch “ implementiert. Zum Beispiel:

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

Wenn das Abgleichen desselben regulären Ausdrucks mit der Zielzeichenfolge zu einer vollständigen Übereinstimmung führt, wird diese wie gewohnt gemeldet:

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

Ein weiteres Beispiel mit einem anderen Muster, das zeigt, dass eine vollständige Übereinstimmung einer teilweisen vorgezogen wird:

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"

In diesem Fall stimmt das Teilmuster „ abc\\w+X “ teilweise mit der Suchzeichenfolge überein; das Teilmuster „ def “ stimmt jedoch vollständig mit der Suchzeichenfolge überein, weshalb eine vollständige Übereinstimmung gemeldet wird.

Werden beim Abgleich mehrere Teilübereinstimmungen gefunden (aber keine vollständige Übereinstimmung), meldet das Objekt „ QRegularExpressionMatch “ die erste gefundene Übereinstimmung. Zum Beispiel:

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"

Inkrementeller/mehrsegmentiger Abgleich

Der inkrementelle Abgleich ist ein weiterer Anwendungsfall des Teilabgleichs. Angenommen, wir möchten die Vorkommen eines regulären Ausdrucks in einem großen Text finden (d. h. Teilzeichenfolgen, die mit dem regulären Ausdruck übereinstimmen). Dazu möchten wir den großen Text in kleineren Blöcken an die regulären Ausdrucks-Engines „übergeben“. Das offensichtliche Problem ist: Was passiert, wenn sich die Teilzeichenfolge, die mit dem regulären Ausdruck übereinstimmt, über zwei oder mehr Teile erstreckt?

In diesem Fall sollte die Engine für reguläre Ausdrücke eine Teilübereinstimmung melden, damit wir den Abgleich unter Hinzufügung neuer Daten wiederholen und (schließlich) eine vollständige Übereinstimmung erhalten können. Dies bedeutet, dass die Engine für reguläre Ausdrücke davon ausgehen darf, dass sich hinter dem Ende der Suchzeichenfolge noch weitere Zeichen befinden. Dies ist nicht wörtlich zu nehmen – die Engine wird niemals versuchen, auf ein Zeichen zuzugreifen, das nach dem letzten Zeichen der Suchzeichenfolge liegt.

QRegularExpression implementiert dieses Verhalten bei Verwendung des Übereinstimmungstyps „ PartialPreferFirstMatch “. Dieser Übereinstimmungstyp meldet eine Teilübereinstimmung, sobald sie gefunden wird, und andere Übereinstimmungsalternativen werden nicht ausprobiert (selbst wenn sie zu einer vollständigen Übereinstimmung führen könnten). Zum Beispiel:

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

Dies geschieht, weil beim Abgleichen des ersten Zweigs des Alternativoperators eine teilweise Übereinstimmung gefunden wird und der Abgleich daher beendet wird, ohne den zweiten Zweig zu versuchen. Ein weiteres Beispiel:

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

Dies veranschaulicht ein auf den ersten Blick vielleicht kontraintuitives Verhalten von Quantoren: Da „ ? “ gierig ist, versucht die Engine zunächst, den Abgleich nach dem Abgleich von „ "abc" “ fortzusetzen; doch dann erreicht der Abgleich das Ende der Suchzeichenfolge, weshalb ein Teilabgleich gemeldet wird. Noch überraschender ist dies im folgenden Beispiel:

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

Dieses Verhalten lässt sich leicht nachvollziehen, wenn man bedenkt, dass die Suchmaschine davon ausgeht, dass die Suchzeichenfolge lediglich eine Teilzeichenfolge des gesamten Textes ist, in dem nach einer Übereinstimmung gesucht wird (das heißt, wie bereits erwähnt, geht die Suchmaschine davon aus, dass sich hinter dem Ende der Suchzeichenfolge weitere Zeichen befinden).

Da der Quantor „ * “ gierig ist, könnte die Meldung eines vollständigen Treffers ein Fehler sein, da nach dem aktuellen Such "abc" „ "abc" “ noch weitere Vorkommen folgen könnten. Beispielsweise hätte der vollständige Text „abcabcX“ lauten können, und daher wäre die richtige Übereinstimmung (im vollständigen Text) „ "abcabc" “ gewesen; durch den Abgleich nur mit dem führenden „ "abc" “ erhalten wir stattdessen eine teilweise Übereinstimmung.

Fehlerbehandlung

Ein `QRegularExpression`-Objekt kann aufgrund von Syntaxfehlern in der Musterzeichenfolge ungültig sein. Die Funktion ` isValid()` gibt „true“ zurück, wenn der reguläre Ausdruck gültig ist, andernfalls „false“:

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

Weitere Informationen zum jeweiligen Fehler erhalten Sie durch Aufruf der Funktion ` errorString()`; darüber hinaus gibt die Funktion ` patternErrorOffset()` den Offset innerhalb der Musterzeichenfolge zurück

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

Wird ein Abgleich mit einem ungültigen `QRegularExpression` versucht, ist das zurückgegebene ` QRegularExpressionMatch `-Objekt ebenfalls ungültig (d. h., seine Funktion ` isValid()` gibt `false` zurück). Dasselbe gilt für den Versuch eines globalen Abgleichs.

Nicht unterstützte Funktionen von Perl-kompatiblen regulären Ausdrücken

QRegularExpression unterstützt nicht alle Funktionen, die in Perl-kompatiblen regulären Ausdrücken verfügbar sind. Am auffälligsten ist dabei, dass doppelte Namen für Erfassungsgruppen nicht unterstützt werden; deren Verwendung kann zu undefiniertem Verhalten führen.

Dies kann sich in einer zukünftigen Version von Qt ändern.

Debugging von Code, der QRegularExpression verwendet

QRegularExpression nutzt intern einen Just-in-Time-Compiler (JIT), um die Ausführung des Abgleichalgorithmus zu optimieren. Der JIT macht ausgiebig Gebrauch von selbstmodifizierendem Code, was dazu führen kann, dass Debugging-Tools wie Valgrind abstürzen. Sie müssen alle Prüfungen auf selbstmodifizierenden Code aktivieren, wenn Sie Programme debuggen möchten, die QRegularExpression verwenden (zum Beispiel die Befehlszeilenoption „ --smc-check “ von Valgrind). Der Nachteil bei der Aktivierung solcher Prüfungen ist, dass Ihr Programm deutlich langsamer läuft.

Um dies zu vermeiden, ist der JIT standardmäßig deaktiviert, wenn Sie Qt im Debug-Modus kompilieren. Es ist möglich, die Standardeinstellung zu überschreiben und die Verwendung des JIT (sowohl im Debug- als auch im Release-Modus) zu aktivieren oder zu deaktivieren, indem Sie die Umgebungsvariable ` QT_ENABLE_REGEXP_JIT ` auf einen Wert ungleich Null bzw. auf Null setzen.