fn:matches

(Auszug aus "XSLT 2.0 & XPath 2.0" von Frank Bongers, Kapitel 5.)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

   

Kategorie: Stringfunktionen – Patternmatching

Herkunft: XPath 2.0

Rückgabewert: Ein boolescher Wert xs:boolean; der Wert true, wenn der Eingabestring dem Vergleichsmuster des RegEx entspricht, andernfalls der Wert false.

Aufruf/Argumente:

fn:matches($eingabestring?, $reg-ex, $flags?)

$eingabestring:
Ein Eingabestring xs:string, von dem überprüft werden soll, ob der reguläre Ausdruck des zweiten Arguments auf ihn (oder Teile von ihm) erfolgreich anzuwenden ist. Wird an dieser Stelle die leere Sequenz über­geben, so gibt die Funktion diese zurück.

$reg-ex:
Obligatorisch. Das Argument besteht aus einem regulären Aus­druck (regular expression), der zur Prüfung des Strings herangezogen wird.

$flags:
Optional. Mittels des Flags-Arguments kann die Wirkung des regu­lären Ausdrucks bestimmt werden. Wird kein Flags-Argument übergeben, so prüft der reguläre Ausdruck erstens »case-sensitive« und betrachtet zweitens den Eingabestring als geschlossene (nicht zeilenorientierte) Zeichenkette.

Verwendungszweck:

Die Funktion fn:matches() wird zur Untersu­chung eines Eingabestrings verwendet und gibt einen booleschen Wert zurück, der beschreibt, ob der ebenfalls übergebene reguläre Ausdruck auf den String passt (match). Es wird keine Änderung am Eingabestring vorgenommen.

Ein Match tritt dann auf, wenn der reguläre Ausdruck an irgendeiner Stelle des untersuchten Strings zutrifft. Hierbei werden Groß-/Kleinschreibung beachtet (case-sensitive), Zeilenumbrüchzeichen innerhalb des übergebenen Strings wer­den als normale Zeichen gewertet (Stringmodus).

Um das Verhalten des regulären Ausdrucks zu modifizieren, darf zusätzlich zum Eingabestring und dem regulären Ausdruck als drittes Argument ein String als sogenanntes »Flag« übergeben werden. Die erlaubten Flags sind an die Konventionen von Perl angelehnt.

Reguläre Ausdrücke – Kurzübersicht:

Größtenteils sind reguläre Ausdrücke in XPath an die entsprechende Syntax aus Perl angelehnt, jedoch gibt es diverse Vereinfachungen und damit auch wesentliche Abweichungen. In Perl gültige reguläre Ausdrücke las­sen sich daher nicht in jedem Fall in XPath mit gleicher Wirkung einsetzen. Eine ausführliche Einführung in reguläre Ausdrücke ist aus Platzgründen an dieser Stelle nicht möglich. Deshalb erfolgt lediglich eine kurze Übersicht über in regulären Ausdrücken verwendete Metazeichen und ihre jeweilige Bedeutung.

Setzen von Flags mit dem $flags-Argument:

Das Argument darf aus den Einzelbuchstaben m, i, s, x oder (in unbestimmter Reihenfolge) aus sinnvollen Kombinationen von diesen besteht. Auch der leere String (bzw. die leere Sequenz) ist gestattet. Ein ungültiges (also von den erlaubten Zeichen abweichendes) Flag-Argument quittiert der Prozessor mit der Fehlermeldung »Invalid regular expression. flags« (err:FORX0001).

Achtung – Abweichung zu Flags in Perl-Syntax: Das Perl-Flag g (»global«) wird in XPath nicht unterstützt!

Flagsymbol	Beschreibung
i	»ignore« – ignoriert für die Matches die Groß-/Kleinschreibung im untersuchten String.
m	»multiline« – beachtet Zeilenumbrüche im untersuchten String (erlaubt einen mehrfachen Match durch die Pattern ^ und $).
s	Schaltet in den sogenannten »dot-all«-Modus um. Erläuterung: Beeinflusst wird das Verhalten des Metazeichens ».« (dot) – ohne gesetztes s-Flag trifft dieses Metazeichen auf alle Zeichen (auch Whitespace!) zu, außer auf das Zeilenumbruchzeichen #x0A (NL).
x	Deaktiviert die Beachtung der Whitespace-Zeichen #x9, #xA, #xD und #x20 innerhalb des regulären Ausdrucks. Ist das Flag nicht gesetzt, werden Whitespace-Zeichen hingegen als Teil des Ausdrucks betrachtet und für den Match berücksichtigt. Erläuterung: Das gesetzte Flag x ermöglicht, längere reguläre Ausdrücke durch den Einsatz von Zeilenumbrüchen und Tabulatoren übersichtlicher zu gestalten.
''	Der leere String – dieser ist als Wert ausdrücklich gestattet. Er entspricht der Nicht-Übergabe eines Flag-Arguments.

Tabelle: In XPath erlaubte Symbole für Flags in regulären Ausdrücken. 

Flag 'i':

Der Wert 'i' (ignore) bewirkt das Ignorieren von Groß-/Klein­schreibung im untersuchten String. Ein Match wird auch dann gemeldet, wenn der gefundene Teilstring in der Schreibweise nicht mit dem Pattern überein­stimmt:

fn:matches('ABC', 'a', 'i')

ergibt true, weil durch das Flag 'A' und 'a' gleichermaßen gefunden werden.

fn:matches('ABC','a')

ergibt dagegen false, weil ohne Flag die Groß-/Kleinschreibung beachtet wird. 

Flag 'm':

Das Flag 'm' schaltet die Interpretation des Eingabestrings von Stringmodus (string mode, Default) in Mehrzeilenmodus (multiline mode) um. Mit gesetztem Flag 'm' wird die übergebene Zeichenkette als »mehrzeilig« interpretiert, in ihr enthaltene Zeilenumbruchzeichen #x0A also als Zeilenbe­grenzer betrachtet. Dies wirkt sich auf die Arbeit der Metazeichen ^ und $ aus, die Anfang und Ende einer Zeichenkette erkennen. In diesem Fall wird dies auf Zeilenanfang und -ende ausgeweitet:

fn:matches('abc
            def', 'abc$', 'm')

ergibt true, weil durch das multiline-Flag der Zeilenumbruch, für den das Metazeichen $ steht, hinter dem Teilstring abc als Zeilenende erkannt wird.

fn:matches('abc
            def', 'abc$')

ergibt dagegen false, da die Zeichenkette in diesem Fall als Ganzes untersucht wird (im Stringmodus). Sie besitzt also für die Funktion nur ein erkennbares Ende, nämlich das Stringende selbst.

Metazeichen	Beschreibung
.	Der Punkt steht für jedes beliebige Zeichen, inklusive des Zeilenumbruchs (#x0A), solange nicht explizit ein m-Flag gesetzt wurde.
^	Der (vorangestellte) Zirkumflex steht für den Anfang der Zeichenkette bzw. den Zeilenanfang bei gesetztem Flag m; dient auch als Negation in Zeichenlisten.
$	Das (nachgestellte) Dollarzeichen steht für das Ende der Zeichenkette bzw. das Zeilenende bei gesetzem Flag m.
|	Das Pipe-Symbol wird im Sinne von 'oder' verwendet, um zwischen Zeichen oder Gruppen zu wählen.
+	Quantifier; vorangehendes Zeichen kommt ein- oder mehrmals vor.
*	Quantifier; vorangehendes Zeichen kommt kein- oder mehrmals vor.
?	Quantifier; vorangehendes Zeichen kommt kein- oder einmal vor.
{n}	Quantifier; vorangehendes Zeichen kommt genau n-mal vor.
{n,}	Quantifier; vorangehendes Zeichen kommt mindestens n-mal vor.
{n, m}	Quantifier; vorangehendes Zeichen kommt mindestens n-mal, aber höchstens m-mal vor.
( )	Runde Klammern dienen innerhalb des Patterns zur Bildung von Subgruppen für Backreferences.
[ ]	Eckige Klammern dienen zur Angabe von Zeichenlisten, -klassen (char classes) oder -bereichen (char ranges).

Tabelle: Erlaubte Metazeichen innerhalb regulärer Ausdrücke. 

Metazeichen '.':

Der Punkt '.' steht für jedes beliebige Zeichen, inklu­sive des Zeilenumbruchzeichens, wenn das m-Flag nicht explizit gesetzt wurde (dies ist genau umgekehrt zu dem Verhalten in Perl).

fn:matches($eingabestring, '.')

gibt immer true zurück, wenn $eingabestring ein beliebiges Zeichen ent­hält, also nicht leer ist. 

Metazeichen '^':

Das Metazeichen '^' wird einem beliebigen Ausdruck vorangestellt, um anzuzeigen, dass sich dieser am Anfang des Strings befinden muss:

fn:matches($eingabestring, '^abc')

gibt dann true zurück, wenn $eingabestring mit 'abc' beginnt.

(Im Zusammenhang mit Zeichenlisten schließt ^ ein Zeichen, dem es vorange­stellt wird, aus.)

Metazeichen '$':

Das Metazeichen '$' wird einem beliebigen Ausdruck nachgestellt, um anzuzeigen, dass sich dieser am Ende des Strings befinden muss:

fn:matches($eingabestring, 'abc$')

gibt dann true zurück, wenn $eingabestring mit 'abc' endet. 

Metazeichen '|':

Das Metazeichen '|' signalisiert Wahlmöglichkeit zwischen zwei Unterpattern:

fn:matches($eingabestring, '^a|b$')

gibt true zurück, wenn $eingabestring mit 'a' beginnt oder mit 'b' endet. 

Metazeichen '+':

Das Metazeichen '+' bezeichnet das ein- oder mehrma­lige Auftreten des ihm vorangehenden Zeichens (hier und in Folge das Metazei­chen '.'):

fn:matches($eingabestring, 'a.+')

gibt true zurück, wenn $eingabestring ein a mit ein oder mehreren beliebi­gen folgenden Zeichen enthält (false, wenn der String leer ist, kein 'a' ent­hält, aus dem 'a' als einzigem Zeichen besteht oder das einzige a am Strin­gende steht). 

Metazeichen '*':

Das Metazeichen '*' bezeichnet das kein- oder mehr­malige Auftreten des Zeichens, das ihm vorangeht:

fn:matches($eingabestring, 'a.*')

gibt true zurück, wenn $eingabestring ein a oder ein a mit einer beliebigen Zahl folgender Zeichen enthält (false, wenn der String leer ist oder kein 'a' enthält).

Soll die Quantifizierer + oder * gierig oder zurückhaltend wirken?
Die Quantifizierer + und * können durch ein nachgestelltes Fragezeichen +? oder *? von 'greedy' (gierig) auf 'reluctant' (nicht gierig) umgestellt werden. Für fn:matches() ist dies zwar bedeutungslos, da es hier nur darauf ankommt, ob überhaupt ein Match auf­tritt, nicht so hingegen bei den Funktionen fn:replace() oder fn:tokenize().

Metazeichen '?':

Das Metazeichen '?' bezeichnet das kein- oder einma­lige Auftreten des Zeichens, das ihm vorangeht:

fn:matches($eingabestring, 'a.?')

gibt true zurück, wenn $eingabestring ein a oder ein a mit einem beliebigen folgenden Zeichen enthält (false, wenn der String leer ist oder kein 'a' ent­hält). 

Metazeichen '{n,m}':

Das Metazeichen '{n,m}' bezeichnet das mindes­tens n-malige und maximal m-malige Auftreten des ihm vorangehenden Zei­chens:

fn:matches($eingabestring, 'a{2,4}')

gibt true zurück, wenn $eingabestring die Zeichenfolge 'aa', 'aaa' oder 'aaaa' enthält. 

Metazeichen '(...)':

Die runden Klammern gruppieren einen Reg-Ex bzw. definieren Unterpattern für Backreferences: 

fn:matches($eingabestring, '(ab)|(cd)')

gibt true zurück, wenn $eingabestring die Teilstrings 'ab' oder 'cd' enthält. Die Funktion fn:matches() verwendet jedoch keine Backreferences, die auf Unterpattern zugreifen – die Verwendung dieser Metazeichen macht also in diesem Zusammenhang keinen Sinn.

Metazeichen '[...]':

Die eckigen Klammern markieren eine Zeichenliste oder einen Zeichenbereich:

fn:matches($eingabestring, '[abc]')

gibt true zurück, wenn $eingabestring die Zeichen a, b oder c enthält.

fn:matches($eingabestring, '[a-d]')

gibt true zurück, wenn $eingabestring eines der Zeichen des Bereichs a bis d, also a, b, c oder d enthält.

Funktionsdefinition:

XPath 1.0:

Funktion nicht verfügbar

XPath 2.0:

fn:matches($input as xs:string?,
           $pattern as xs:string) as xs:boolean?

fn:matches($input as xs:string?,
           $pattern as xs:string,
           $flags as xs:string) as xs:boolean?

   

<< zurück

vor >>