QRegularExpression Class

Detaillierte Beschreibung

Reguläre Ausdrücke, oder regexps, sind ein sehr mächtiges Werkzeug, um Zeichenketten und Texte zu verarbeiten. Dies ist in vielen Kontexten nützlich, z.B.,

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

Gute Referenzen über reguläre Ausdrücke sind unter anderem:

• Mastering Regular Expressions (Third Edition) von Jeffrey E. F. Friedl, ISBN 0-596-52812-4;
• die Manpage pcrepattern(3), die die von PCRE (der Referenzimplementierung von Perl-kompatiblen regulären Ausdrücken) unterstützte Mustersyntax beschreibt;
• die Dokumentation zu regulären Ausdrücken in Perl und das Tutorial zu regulären Ausdrücken in Perl.

Einführung

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

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

QRegularExpression re("a pattern");

Dadurch wird die Musterzeichenkette 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 abschließen müssen:

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

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

In diesem Fall brauchen Sie keine Backslashes im Muster zu verwenden, da alle Zeichen zwischen R"(...)" als rohe Zeichen betrachtet 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"

Muster-Optionen

Die Bedeutung der Musterzeichenkette kann durch Setzen einer oder mehrerer Musteroptionen geändert werden. Es ist zum Beispiel möglich, ein Muster so einzustellen, dass die Groß- und Kleinschreibung nicht beachtet wird, indem die Option QRegularExpression::CaseInsensitiveOption gesetzt wird.

Sie können die Optionen setzen, indem Sie sie an den Konstruktor QRegularExpression übergeben, wie in:

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

Es ist möglich, mit der Funktion patternOptions() die aktuell eingestellten Musteroptionen eines QRegularExpression-Objekts abzurufen:

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 QRegularExpression::PatternOption enum.

Übereinstimmungstyp und Übereinstimmungsoptionen

Die letzten beiden Argumente der Funktionen match() und globalMatch() legen den Übereinstimmungstyp und die Übereinstimmungsoptionen fest. Der Abgleichstyp ist ein Wert der Aufzählung QRegularExpression::MatchType; der "traditionelle" Abgleichsalgorithmus wird durch die Verwendung des Abgleichstyps NormalMatch (die Vorgabe) gewählt. Es ist auch möglich, einen teilweisen Abgleich des regulären Ausdrucks mit einer Betreff-Zeichenkette zu aktivieren: siehe den Abschnitt partial matching für weitere Einzelheiten.

Die Übereinstimmungsoptionen sind ein Satz von einem oder mehreren QRegularExpression::MatchOption Werten. Sie ändern die Art und Weise, wie eine bestimmte Übereinstimmung eines regulären Ausdrucks mit einer Betreff-Zeichenkette durchgeführt wird. Weitere Einzelheiten entnehmen Sie bitte der Dokumentation QRegularExpression::MatchOption enum.

Normaler Abgleich

Um einen Abgleich durchzuführen, können Sie einfach die Funktion match() aufrufen und eine Zeichenkette übergeben, die abgeglichen werden soll. Wir bezeichnen diese Zeichenkette als Betreffzeichenkette. Das Ergebnis der Funktion match() ist ein QRegularExpressionMatch Objekt, mit dem die Ergebnisse des Abgleichs überprüft werden 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

Wenn eine Übereinstimmung erfolgreich ist, kann die (implizite) Erfassungsgruppennummer 0 verwendet werden, um die Teilzeichenkette abzurufen, auf die das gesamte Muster passt (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, eine Übereinstimmung an einem beliebigen Offset innerhalb der Betreffzeichenkette zu beginnen, indem der Offset als Argument der Funktion match() übergeben wird. Im folgenden Beispiel wird "12 abc" nicht gefunden, da die Übereinstimmung bei 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 erfasster Teilstrings

Das Objekt QRegularExpressionMatch enthält auch Informationen über die Teilzeichenketten, die von den Erfassungsgruppen im Musterstring erfasst wurden. Die Funktion captured() gibt die Zeichenkette zurück, die von der n-ten Erfassungsgruppe erfasst wurde:

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

Die Erfassungsgruppen im Muster sind von 1 an nummeriert, und die implizite Erfassungsgruppe 0 wird verwendet, um die Teilzeichenkette zu erfassen, die mit dem gesamten Muster übereinstimmt.

Mit den Funktionen capturedStart() und capturedEnd() können auch der Anfangs- und der End-Offset (innerhalb der betreffenden Zeichenkette) jeder erfassten Teilzeichenkette abgerufen werden:

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 haben eine Überladung mit QString als Parameter, um benannte erfasste Teilstrings 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
}

Globaler Abgleich

Derglobale Abgleich ist nützlich, um alle Vorkommen eines bestimmten regulären Ausdrucks in einer bestimmten Zeichenkette zu finden. Angenommen, wir wollen alle Wörter aus einer gegebenen Zeichenkette extrahieren, wobei ein Wort eine Teilzeichenkette ist, die dem Muster \w+ entspricht.

QRegularExpression::globalMatch gibt ein QRegularExpressionMatchIterator zurück, das ein Java-ähnlicher Vorwärts-Iterator ist, der verwendet werden kann, um über die Ergebnisse zu iterieren. Zum Beispiel:

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

Da es sich um einen Java-ähnlichen Iterator handelt, zeigt die QRegularExpressionMatchIterator unmittelbar vor dem ersten Ergebnis. Jedes Ergebnis wird als QRegularExpressionMatch Objekt zurückgegeben. Die Funktion hasNext() gibt true zurück, wenn es mindestens ein weiteres Ergebnis gibt, und next() gibt das nächste Ergebnis zurück und setzt den Iterator fort. Fortsetzung des vorherigen Beispiels:

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 zu erhalten, ohne den Iterator weiterzuschalten.

Es ist auch möglich, einfach das Ergebnis von QRegularExpression::globalMatch in einer bereichsbasierten for-Schleife zu verwenden, zum Beispiel so:

// 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 Startoffset und eine oder mehrere Übereinstimmungsoptionen an die Funktion globalMatch() zu übergeben, genau wie beim normalen Abgleich mit match().

Teilweiser Abgleich

Eine Teilübereinstimmung liegt vor, wenn das Ende der betreffenden Zeichenkette erreicht ist, aber noch weitere Zeichen benötigt werden, um die Übereinstimmung zu vervollständigen. Beachten Sie, dass eine teilweise Übereinstimmung in der Regel viel ineffizienter ist als eine normale Übereinstimmung, da viele Optimierungen des Übereinstimmungsalgorithmus nicht genutzt werden können.

Eine Teilübereinstimmung muss explizit angefordert werden, indem beim Aufruf von QRegularExpression::match oder QRegularExpression::globalMatch ein Übereinstimmungstyp PartialPreferCompleteMatch oder PartialPreferFirstMatch angegeben wird. Wird eine Teilübereinstimmung gefunden, gibt der Aufruf der Funktion hasMatch() auf dem von match() zurückgegebenen Objekt QRegularExpressionMatch den Wert false zurück, während hasPartialMatch() den Wert true liefert.

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

Beachten Sie, dass die Frage nach einer teilweisen Übereinstimmung immer noch zu einer vollständigen Übereinstimmung führen kann, wenn eine gefunden wird; in diesem Fall gibt hasMatch() true und hasPartialMatch() false zurück. Es kommt nie vor, dass QRegularExpressionMatch sowohl eine teilweise als auch eine vollständige Übereinstimmung meldet.

Teilweise Übereinstimmung ist hauptsächlich in zwei Szenarien nützlich: Validierung von Benutzereingaben in Echtzeit und inkrementelle/mehrteilige Übereinstimmung.

Validierung von Benutzereingaben

Angenommen, wir möchten, dass der Benutzer ein Datum in einem bestimmten Format eingibt, zum Beispiel "MMM tt, jjjj". 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 fängt keine ungültigen Tage ab, aber wir behalten es für die Zwecke des Beispiels bei).

Wir möchten die Eingabe mit diesem regulären Ausdruck überprüfen , während der Benutzer sie eingibt, so dass wir einen Fehler in der Eingabe melden können, sobald er begangen wurde (z. B. 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 entspricht dem regulären Ausdruck im Moment nicht, wird es aber, wenn weitere Zeichen hinzugefügt werden.

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

Insbesondere im letzten Fall möchten wir, dass die Engine für reguläre Ausdrücke eine Teilübereinstimmung meldet: Wir haben das Muster erfolgreich mit der Betreffzeichenkette abgeglichen, aber der Abgleich kann nicht fortgesetzt werden, weil das Ende des Betreffs erreicht wurde. Beachten Sie jedoch, dass der Abgleichsalgorithmus fortfahren und alle Möglichkeiten ausprobieren sollte, und 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 ein Abgleich desselben regulären Ausdrucks mit der Betreffzeichenkette zu einer vollständigen Übereinstimmung führt, wird dies wie üblich 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 gegenüber einer teilweisen Übereinstimmung bevorzugt 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 Betreffzeichenkette überein; das Teilmuster def stimmt jedoch vollständig mit der Betreffzeichenkette überein, so dass eine vollständige Übereinstimmung gemeldet wird.

Wenn beim Abgleich mehrere Teilübereinstimmungen gefunden werden (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/Mehrsegmentabgleich

Inkrementeller Abgleich ist ein weiterer Anwendungsfall des partiellen Abgleichs. Nehmen wir an, wir wollen die Vorkommen eines regulären Ausdrucks in einem großen Text finden (d.h. Teilstrings, die auf den regulären Ausdruck passen). Zu diesem Zweck möchten wir den großen Text in kleineren Stücken an die Maschinen für reguläre Ausdrücke "verfüttern". Das offensichtliche Problem ist, was passiert, wenn die Teilzeichenkette, die mit dem regulären Ausdruck übereinstimmt, sich über zwei oder mehr Abschnitte erstreckt.

In diesem Fall sollte die Engine für reguläre Ausdrücke eine Teilübereinstimmung melden, so dass wir die Übereinstimmung durch Hinzufügen neuer Daten wiederherstellen können und (schließlich) eine vollständige Übereinstimmung erhalten. Dies bedeutet, dass die Engine für reguläre Ausdrücke davon ausgehen kann, dass es noch weitere Zeichen hinter dem Ende der betreffenden Zeichenfolge gibt. Dies ist nicht wörtlich zu nehmen - die Engine wird niemals versuchen, auf ein Zeichen nach dem letzten Zeichen im Betreff zuzugreifen.

QRegularExpression implementiert dieses Verhalten, wenn der Übereinstimmungstyp PartialPreferFirstMatch verwendet wird. Dieser Übereinstimmungstyp meldet eine Teilübereinstimmung, sobald sie gefunden wird, und andere Alternativen werden nicht ausprobiert (auch 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 Abgleich mit dem ersten Zweig des Alternationsoperators eine Teilübereinstimmung gefunden wird und der Abgleich daher abgebrochen wird, ohne den zweiten Zweig zu versuchen. Ein anderes Beispiel:

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

Hier zeigt sich ein scheinbar kontraintuitives Verhalten von Quantoren: Da ? gierig ist, versucht die Maschine zunächst, den Abgleich fortzusetzen, nachdem sie "abc" abgeglichen hat; aber dann erreicht der Abgleich das Ende der Betreffzeichenkette, und daher wird eine teilweise Übereinstimmung gemeldet. 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 ist leicht zu verstehen, wenn wir uns daran erinnern, dass die Suchmaschine davon ausgeht, dass die Betreffzeichenkette nur eine Teilzeichenkette des gesamten Textes ist, in dem wir eine Übereinstimmung suchen (d. h., wie wir bereits sagten, dass die Suchmaschine davon ausgeht, dass es hinter dem Ende der Betreffzeichenkette weitere Zeichen gibt).

Da der Quantifizierer * gierig ist, könnte es ein Fehler sein, eine vollständige Übereinstimmung zu melden, da es nach dem aktuellen Betreff "abc" noch weitere Vorkommen von "abc" geben kann. Der vollständige Text könnte beispielsweise "abcabcX" lauten, und daher wäre die richtige Übereinstimmung (im vollständigen Text) "abcabc"; durch einen Abgleich nur mit dem führenden "abc" erhalten wir stattdessen eine teilweise Übereinstimmung.

Fehlerbehandlung

Es ist möglich, dass ein QRegularExpression-Objekt aufgrund von Syntaxfehlern in der Musterzeichenfolge ungültig ist. 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

Sie können weitere Informationen über den spezifischen Fehler erhalten, indem Sie die Funktion errorString() aufrufen; außerdem 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
    // ...
}

Wenn eine Übereinstimmung mit einem ungültigen QRegularExpression versucht wird, dann ist das zurückgegebene QRegularExpressionMatch Objekt ebenfalls ungültig (d.h. seine isValid() Funktion gibt false zurück). Das Gleiche gilt für den Versuch einer globalen Übereinstimmung.

Nicht unterstützte Perl-kompatible reguläre Ausdrücke Merkmale

QRegularExpression unterstützt nicht alle Funktionen, die in Perl-kompatiblen regulären Ausdrücken verfügbar sind. Das bemerkenswerteste Merkmal ist die Tatsache, dass doppelte Namen für die Erfassung von Gruppen nicht unterstützt werden und dass ihre Verwendung zu undefiniertem Verhalten führen kann.

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

Debugging von Code, der QRegularExpression verwendet

QRegularExpression verwendet intern einen Just-in-Time-Compiler (JIT), um die Ausführung des Matching-Algorithmus zu optimieren. Der JIT macht ausgiebig Gebrauch von sich selbst modifizierendem Code, was Debugging-Tools wie Valgrind zum Absturz bringen kann. Sie müssen alle Prüfungen auf selbstmodifizierenden Code aktivieren, wenn Sie Programme mit QRegularExpression debuggen wollen (z.B. Valgrinds Kommandozeilenoption --smc-check ). Der Nachteil der Aktivierung solcher Prüfungen ist, dass Ihr Programm erheblich langsamer läuft.

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