fn:contains

(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 – Analyse

Herkunft: XPath 1.0

Rückgabewert: Ein Boolescher Wert – true oder false in Abhängigkeit davon, ob ein Teststring im getesteten Ausdruck enthalten ist oder nicht.

Aufruf/Argumente:

fn:contains($teststring?, $vergleichsstring?, $collation-URI?)

$teststring:
Optional. Ein Eingabewert vom Typ String xs:string, für den überprüft werden soll, ob in ihm der als zweites Argument übergebene Vergleichs­string als Substring enthalten ist. Handelt es sich bei dem Argument nicht um einen String, so wird ein Typfehler gemeldet. Die leere Sequenz als Argument wird wie der leere String behandelt. Ist $teststring der leere String, so gibt die Funktion den Wert false zurück. (In XPath 1.0 wird der Wert, falls es sich nicht um einen String handelt, nach den Regeln der Umwandlungsfunktion string() in einen String verwandelt.)

$vergleichsstring:
Optional. Der String xs:string, der auf Vorkommen als Substring im String des ersten Arguments getestet wird. Handelt es sich bei dem Argu­ment nicht um einen String, so wird ein Typfehler gemeldet. Die leere Sequenz wird wie der leere String behandelt. Ist $vergleichsstring der leere String, so gibt die Funktion den Wert true zurück (der leere String ist in einem anderen String stets enthalten, sofern dieser nicht selbst leer ist).

$collation-URI:
Optional. Das dritte Argument besteht aus einem String xs:string, der den URI-String der anzuwendenden Collation benennt. Der Wert muss lexikalisch dem Typ xs:anyURI entsprechen. Wird kein drittes Argument übergeben, so wird für den Vergleich die Unicode Codepoint Collation herangezogen. (XPath 1.0 kennt keine Collations und nimmt dement­sprechend kein drittes Argument entgegen.)

Verwendungszweck:

Der Rückgabewert von fn:contains() ist true, wenn der überprüfte String den Test­string enthält oder mit ihm identisch ist. Formal ausgedrückt, muss der getestete String eine zusammenhängende Folge von Zeichen aufweisen, deren Unicode-Werte den korrespondierenden Zeichen im Test­string entsprechen. In allen anderen Fällen ist der Rückgabewert der Funktion false.

Im einfachsten Fall werden unmittelbar zwei Strings übergeben:

fn:contains("abc","b") ergibt true

Sonderfälle und Anmerkungen:

Wird als Vergleichsstring der leere String oder – gleichwertig – die leere Sequenz übergeben, so ist der Rückgabewert immer true. Ist dagegen der getestete String selbst leer bzw. wird als erstes Argument die leere Sequenz übergeben, so ist der Rückgabewert stets false – es sei denn, der Vergleichsst­ring wäre gleichfalls ein leerer String.

Es ist möglich, mit Hilfe des optionalen dritten Funktionsarguments eine vor­definierte Vergleichsliste (Collation) für den Textvergleich heranzuziehen – beispielsweise um »Fluß« und »Fluss«, »Jäger« und »Jaeger« als sinngemäß identisch erkennen zu können. Die Art und Weise, wie die Collation eingebun­den wird, ist implementationsabhängig. Der String, der die Verknüpfung zur Collation herstellt, muss lexikalisch dem Typ xs:anyURI entsprechen, wird aber als xs:string übergeben.

Wird kein entsprechendes drittes Argument übergeben, so findet der String­vergleich anhand der Unicode Codepoint Collation statt. Es wird nicht die Default-Collation des Systems verwendet. Das Verhalten von fn:contains() geht damit konform mit denjenigen String­funktionen, die reguläre Ausdrücke verwenden, wie fn:matches(), fn:replace() und fn:tokenize(). Jene Funktionen arbeiten ebenfalls auf Basis der Unicode Codepoint Collation, bei ihnen kann jedoch keine andere Collation zugewiesen werden.

Beispiele:

Beispiel 1 – Vergleichsstring im Eingabestring enthalten:

fn:contains('Beispiel', 'eis')

gibt true zurück.

Der Vergleichsstring ist im Eingabestring enthalten – die Funktion gibt daher den booleschen Wert true zurück.

Beispiel 2 – Vergleichsstring im Eingabestring nicht enthalten:

fn:contains('Beispiel', 'nein')

gibt false zurück.

Der Vergleichs­string ist im Eingabe­string nicht enthalten – die Funktion gibt daher den Booleschen Wert false zurück.

Beispiel 3 – Vergleichsstring ist der leere String:

fn:contains('Beispiel', '')

gibt true zurück.

Der Vergleichsstring ist der leere String. Dieser gilt als in einem beliebigen Test­string enthalten – die Funktion gibt daher den booleschen Wert true zurück. Dies gilt auch dann, wenn der Test­string ebenfalls leer ist:

fn:contains('', '')

gibt ebenfalls true zurück.

Beispiel 4 – Verwendung einer Collation:

Wird zur Auswertung des Textvergleichs eine Collation als Textvergleichsanweisung hinzugezogen, die bestimmte Zeichen als "zu ignorieren" festlegt, so werden diese vor dem Vergleich aus dem zweiten Argumentstring entfernt.

fn:contains('Beispiel', '-e-i-s-', BeispielCollation)

gibt true zurück. Angenommen, der Bindestrich wird innerhalb von BeispielCollation als "zu ignorieren" definiert, so wird der String '-e-i-s-' als 'eis' interpretiert. Der hier vorgenommene Vergleich entspricht also:

fn:contains('Beispiel', 'eis')

und ergibt demzufolge true. Enthält $vergleichsstring ausschließlich zu ignorierende Zeichen (soll z.B. zusätzlich auch * ignoriert werden), so wird er wie der leere String gewertet:

fn:contains('Beispiel', '-*-*-*-'‚ BeispielCollation)

ergibt true, da es fn:contains('Beispiel', '') entspricht.

Beispiel 5 – Formulierung einer Bedingung:

Die Suche nach einem zusammengesetzten Begriff, der in nicht klar definierter Form vorliegt, kann durch fn:contains() zwar erleichtert werden, hat aber trotzdem Tücken. Angenommen, in einer Variablen $autorname sei der Name eines Buchautors abgespeichert:

<xsl:if test="fn:contains($autorname, 'Karl') and fn:contains($autorname, 'May')">
  <!-- Sequence Constructor -->
</xsl:if>

Dieser Test ist erfolgreich für $autorname="Karl May", $autorname="May, Karl", aber in der vorgegebenen Form eben auch für $autorname="Karlheinz Mayer". In XPath 1.0 kann ohne reguläre Ausdrücke, die hier noch nicht vorge­sehen sind, nicht ohne weiteres nach Wortbegrenzungen gesucht werden.

Funktionsdefinition:

XPath 1.0:

contains(string, string) => boolean

XPath 2.0:

fn:contains($arg1 as xs:string?,
            $arg2 as xs:string?) as xs:boolean

fn:contains($arg1 as xs:string?,
            $arg2 as xs:string?,
            $collation as xs:string) as xs:boolean

In XPath 1.0 ist die Überprüfung nach Unicode-Wert auf Grund der Abwesen­heit von Collations nicht in jedem Fall so eindeutig, wie es zu wünschen wäre: Zeichen, die Akzente, Tilden oder ähnliche Beifügungen enthalten, also als zusammengesetztes (composite) Zeichen vorliegen, können in Unicode auf ver­schiedene Arten ausgedrückt sein. Ein Zeichenvergleich schlägt jedoch für optisch identisch repräsentierte, aber unterschiedlich kodierte Zeichen fehl.

   

<< zurück

vor >>