Subroutine regexec

Online bearbeiten

Zweck

Vergleicht die durch den Wert des Parameters String angegebene nullterminierte Zeichenkette mit dem kompilierten einfachen oder erweiterten regulären Ausdruck Preg, der zuvor durch einen Aufruf des Unterprogramms regcomp kompiliert worden sein muss.

Bibliothek

Standard-C-Bibliothek (libc. a)

Syntax

#include <regex.h>
int regexec (Preg, String, NMatch, PMatch, EFlags)
const regex_t * Preg;
const char * String;
size_t  NMatch;
regmatch_t * PMatch;
int  EFlags;

Beschreibung

Das Unterprogramm regexec vergleicht die null-terminierte Zeichenkette im Parameter String mit dem kompilierten einfachen oder erweiterten regulären Ausdruck im Parameter Preg, der durch einen früheren Aufruf des Unterprogramms regcomp initialisiert wurde. Wird eine Übereinstimmung gefunden, gibt die Unterroutine regexec den Wert 0 zurück. Die Unterroutine regexec gibt einen Wert ungleich Null zurück, wenn sie keine Übereinstimmung oder einen Fehler findet.

Wenn der NMatch-Parameter den Wert 0 hat oder wenn das REG_NOSUB-Flag beim Aufruf des Unterprogramms regcomp gesetzt wurde, ignoriert das Unterprogramm regexec den PMatch-Parameter. Andernfalls verweist der Parameter PÜbereinstimmung auf ein Array mit mindestens der Anzahl der Elemente, die durch den Parameter NÜbereinstimmung angegeben werden. Das Unterprogramm regexec füllt die Elemente des Arrays, auf das der Parameter PMatch zeigt, mit den Offsets der Teilstrings des Parameters String. Die Offsets entsprechen den Klammerausdrücken des ursprünglichen Musterparameters, der im Unterprogramm regcomp angegeben wurde.

Die Struktur pmatch.rm_so ist der Byte-Offset des Beginns der Teilzeichenkette, und die Struktur pmatch.rm_eo ist um eins größer als der Byte-Offset des Endes der Teilzeichenkette. Der Unterausdruck I beginnt bei der I . übereinstimmenden linken runden Klammer, beginnend mit 1. Das Element 0 des Arrays entspricht dem gesamten Muster. Nicht verwendete Elemente des Parameters PMatch werden bis zum Wert PMatch[NMatch-1] mit -1 aufgefüllt. Wenn mehr als die durch den NMatch-Parameter angegebene Anzahl von Unterausdrücken (der Pattern-Parameter selbst zählt als Unterausdruck), werden nur die ersten NMatch-1-Unterausdrücke aufgezeichnet.

Wenn ein einfacher oder erweiterter regulärer Ausdruck abgeglichen wird, kann jeder beliebige Klammerunterausdruck des Parameters Muster mit mehreren unterschiedlichen Unterzeichenfolgen des Parameters Zeichenfolge übereinstimmen. Andernfalls stimmt sie möglicherweise mit keiner Unterzeichenfolge überein, obwohl das Muster als Ganzes übereinstimmt.

Die folgenden Regeln werden verwendet, um festzulegen, welche Unterzeichenfolgen im Parameter PÜbereinstimmung gemeldet werden sollen, wenn reguläre Ausdrücke übereinstimmen:

  • Wenn ein Unterausdruck in einem regulären Ausdruck mehrmals an der Übereinstimmung beteiligt war, wird der Offset der letzten übereinstimmenden Teilzeichenkette im PMatch-Parameter angegeben.
  • Wenn ein Unterausdruck nicht an einer Übereinstimmung teilgenommen hat, ist der Byte-Offset im PMatch-Parameter ein Wert von -1. Ein Unterausdruck nimmt nicht an einer Übereinstimmung teil, wenn eine der folgenden Bedingungen zutrifft:
    • Ein * (Sternchen) oder {\} (Backslash, linke Klammer, Backslash, rechte Klammer) erscheint unmittelbar nach dem Unterausdruck in einem einfachen regulären Ausdruck.
    • An * (Sternchen), ? (Fragezeichen) oder { } (linke und rechte geschweifte Klammern) unmittelbar nach dem Unterausdruck in einem erweiterten regulären Ausdruck erscheint und der Unterausdruck nicht übereinstimmt (0 Mal übereinstimmt).
    • Ein | (Pipe) wird in einem erweiterten regulären Ausdruck verwendet, um entweder den Unterausdruck, der nicht übereinstimmt, oder einen anderen Unterausdruck auszuwählen, und der andere Unterausdruck stimmt überein.
  • Wenn ein Unterausdruck in einem Unterausdruck enthalten ist, beziehen sich die Daten im PMatch-Parameter auf den letzten solchen Unterausdruck.
  • Wenn ein Unterausdruck in einem Unterausdruck enthalten ist und die Byte-Offsets im PMatch-Parameter den Wert -1 haben, haben die Zeiger im PMatch-Parameter ebenfalls den Wert -1.
  • Wenn ein Unterausdruck mit einer Zeichenfolge der Länge Null übereinstimmt, beziehen sich die Offsets im PMatch-Parameter auf das Byte, das unmittelbar auf die übereinstimmende Zeichenfolge folgt.

Wenn das REG_NOSUB-Flag im cflags-Parameter im Aufruf des Unterprogramms regcomp gesetzt wurde und der NMatch-Parameter im Aufruf des Unterprogramms regexec ungleich 0 ist, ist der Inhalt des PMatch-Arrays nicht spezifiziert.

Wenn das Flag REG_NEWLINE beim Aufruf des Unterprogramms regcomp im Parameter cflags nicht gesetzt wurde, wird ein Zeilenvorschubzeichen im Parameter pattern oder String wie ein normales Zeichen behandelt. Wenn das REG_NEWLINE-Flag beim Aufruf des Unterprogramms regcomp gesetzt wurde, wird das Zeilenumbruchzeichen wie ein normales Zeichen behandelt, außer wie folgt:

  • Ein Zeilenumbruch im String-Parameter wird nicht durch einen Punkt außerhalb eines Klammerausdrucks oder durch irgendeine Form einer nicht übereinstimmenden Liste ausgeglichen. Ein nicht übereinstimmender Listenausdruck beginnt mit einem ^ (Zirkumflex) und gibt eine Liste an, die einem beliebigen Zeichen oder Sortierfolgeelement und dem Ausdruck in der Liste nach dem führenden Winkelzeichen entspricht. Zum Beispiel kann der reguläre Ausdruck[^abc]passt auf jedes Zeichen außera,boderc. Der Zirkumflex hat diese besondere Bedeutung nur, wenn er das erste Zeichen in der Liste ist, unmittelbar nach der linken Klammer.
  • Ein ^ (Zirkumflex) im Parameter pattern, wenn es zur Angabe der Ausdrucksverankerung verwendet wird, entspricht der Zeichenfolge mit der Länge Null unmittelbar nach einem Zeilenumbruch im Parameter String, unabhängig von der Einstellung des Flags REG_NOTBOL.
  • Ein $ (Dollarzeichen) im Pattern-Parameter passt, wenn es zur Angabe der Ausdrucksverankerung verwendet wird, unabhängig von der Einstellung des REG_NOTEOL-Flags auf die Zeichenfolge mit der Länge Null unmittelbar vor einem Zeilenumbruch im String-Parameter.

Parameter

Element Beschreibung
Vorg. Enthält den kompilierten einfachen oder erweiterten regulären Ausdruck für den Vergleich mit dem Parameter Zeichenfolge .
string Enthält die Daten, die abgeglichen werden sollen.
NÜbereinstimmung Enthält die Anzahl der abzugleichenden Unterausdrücke.
PÜbereinstimmung Enthält das Array von Offsets im Parameter Zeichenfolge , die dem entsprechenden Unterausdruck im Parameter Vorg. entsprechen.
EFlags Enthält das bitweise inklusive ODER von 0 oder mehr der Flags, die das Verhalten der anpassungsfähigen regexec-Unterroutine steuern.

Der Parameter EFlags ändert die Interpretation des Inhalts des Parameters Zeichenfolge . Es ist das bitweise inklusive ODER von 0 oder mehr der folgenden Flags, die in der Datei regex.h definiert sind:

REG_NOTBOL
Das erste Zeichen der Zeichenfolge, auf die der Parameter Zeichenfolge verweist, ist nicht der Anfang der Zeile. Daher passt das ^ (Zirkumflex), wenn es als Sonderzeichen verwendet wird, nicht an den Anfang des String-Parameters.
REG_NOTEOL
Das letzte Zeichen der Zeichenfolge, auf die der Parameter Zeichenfolge verweist, ist nicht das Ende der Zeile. Daher passt das $ (Dollarzeichen), wenn es als Sonderzeichen verwendet wird, nicht an das Ende des String-Parameters.

Rückgabewerte

Bei erfolgreichem Abschluss gibt das Unterprogramm regexec den Wert 0 zurück, um anzuzeigen, dass der Inhalt des String-Parameters mit dem Inhalt des Pattern-Parameters übereinstimmt, oder um anzuzeigen, dass keine Übereinstimmung vorliegt. Der REG_NOMATCH-Fehler ist in der Datei regex.h definiert.

Fehlercodes

Wenn das Unterprogramm regexec nicht erfolgreich ist, gibt es einen Wert ungleich Null zurück, der die Art des Problems angibt. Die folgenden Makros für mögliche Fehlercodes, die zurückgegeben werden können, sind in der Datei regex.h definiert:

Element Beschreibung
REG_NOMATCH Gibt an, dass der einfache oder erweiterte reguläre Ausdruck keine Übereinstimmung finden konnte.
REG_BADPAT Gibt einen ungültigen regulären Basisausdruck oder erweiterten regulären Ausdruck an.
REG_ECOLLATE Gibt ein ungültiges Sortierfolgeelement an, auf das verwiesen wird.
REG_ECTYPE Gibt eine ungültige Zeichenklassenreferenz an.
REG_EESCAPE Zeigt ein nachgestelltes \ (Backslash) im Muster an.
REG_ESUBREG Zeigt eine Zahl in\digitnicht gültig oder fehlerhaft ist.
REG_EBRACK Zeigt ein [ ] (linke und rechte Klammer) Ungleichgewicht an.
REG_EPAREN Zeigt ein \ ( \ ) (Backslash, linke Klammer, Backslash, rechte Klammer) oder ( ) (linke und rechte Klammer) Ungleichgewicht an.
REG_EBRACE Zeigt ein \ { \ } (Backslash, linke Klammer, Backslash, rechte Klammer) Ungleichgewicht.
REG_BADBR Zeigt an, dass der Inhalt von \ { \ } (Backslash, linke Klammer, Backslash, rechte Klammer) ist unbrauchbar (keine Zahl, Zahl zu groß, mehr als zwei Zahlen oder erste Zahl größer als zweite).
REG_ERANGE Zeigt einen unbrauchbaren Endpunkt im Bereichsausdruck an.
REG_ESPACE Zeigt eine abnormale Speicherbedingung an.
REG_BADRPT Zeigt eine ? (Fragezeichen), * (Sternchen) oder + (Pluszeichen), denen kein gültiger einfacher oder erweiterter regulärer Ausdruck vorausgeht.

Wenn der Wert des Preg-Parameters des Unterprogramms regexec kein kompilierter einfacher oder erweiterter regulärer Ausdruck ist, der vom Unterprogramm regcomp zurückgegeben wird, ist das Ergebnis undefiniert.

Beispiele

Das folgende Beispiel zeigt, wie das REG_NOTBOL-Flag mit der Unterroutine regexec verwendet werden kann, um alle Teilzeichenfolgen in einer Zeile zu finden, die mit einem vom Benutzer angegebenen Muster übereinstimmen. (Der Einfachheit halber wird in diesem Beispiel nur eine sehr geringe Fehlerprüfung durchgeführt.)

(void) regcomp (&re, pattern, 0) ;
/* this call to regexec finds the first match on the line */
error = regexec (&re, &buffer[0], 1, &pm, 0) ;
while (error = = 0) {   /* while matches found */
<subString found between pm.r._sp and pm.rm_ep>
/* This call to regexec finds the next match */
error = regexec (&re, pm.rm_ep, 1, &pm, REG_NOTBOL) ;