fn:substring

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

Herkunft: XPath 1.0

Rückgabewert: Ein String xs:string; jener Teilstring eines Eingabestrings, dessen Beginn und Länge durch die ebenfalls übergebenen Zahlenwerte für Startindex und Zeichenzahl bestimmt wird.

Aufruf/Argumente:

fn:substring($eingabewert, $startindex, $laenge?)

$eingabewert:
Obligatorisch. Ein String xs:string; der zu bearbeitende Eingabestring. Handelt es sich bei dem Argument nicht um einen String, so wird ein Typfehler gemeldet. Die leere Sequenz ist als Wert zugelassen und wird wie der leere String behandelt. 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.

$startindex:
Obligatorisch. Das zweite Argument muss eine Zahl xs:double sein, die die Position des ersten Zeichens des Eingabestrings bestimmt, das im Ergebnisstring enthalten sein soll. Ist dieses Argument keine Zahl, so wird es nach den Regeln von fn:number() in eine Zahl umgewandelt. Ergibt sich hierbei eine Bruchzahl, so wird mit fn:round() gerundet.

$laenge:
Optional. Das dritte Argument muss, wenn es übergeben wird, ebenfalls eine Zahl xs:double sein, die die Länge des zu extrahierenden Subst­rings in Zeichen bestimmt. Ist das Argument keine Zahl, so wird es nach den Regeln von fn:number() in eine Zahl umgewandelt und gegebenenfalls gerun­det. Wird kein drittes Argument übergeben, über die Länge des Substrings also keine Angabe gemacht, so wird ein Substring ab dem Startindex bis zum Ende des Eingabestrings erzeugt (intern nimmt das Argument quasi den Wert +INF an).

Verwendungszweck:

Die Funktion fn:substring() entnimmt aus einem Eingabestring einen Teilstring mit definiertem Anfang und definierbarer Länge. Sinnvollerweise wird der Startindex des Substrings durch eine ganze, positive Zahl angegeben.

Für den Fall, dass sich die Werte für Startindex und/oder Substringlänge aus der Bewertung eines Ausdrucks ergeben, werden auf diese gegebenenfalls imp­lizit die Funktionen fn:number() und fn:round() angewendet.

Für den Fall eines Startindexes kleiner Null, ist festgelegt, dass als Substring ab dieser virtuellen Position ausgegeben wird. Ebenso wird für einen Startin­dex, der größer ist als die Stringlänge des Eingabestrings, als Substring stets ein leerer String zurückgegeben. Damit sind auch die Fälle abgedeckt, dass – bei­spielsweise aus der Bewertung eines Ausdrucks – der Startindex plus oder minus Unendlich sein könnte (jeweils leerer String).

Ähnliches gilt für die Längenangabe des Substrings. Ist sie gleich Null oder negativ (kleiner Null), so wird ein leerer String zurückgegeben. Übersteigt die Längenangabe ab dem Startindex die verbleibende Länge des Eingabestrings, so wird nur der Reststring ab dem Startindex ausgegeben (keine Auffüllung mit Leerzeichen).

Die Funktion gibt den leeren String zurück, wenn statt eines Eingabestrings die leere Sequenz übergeben wurde.

Als Zeichen gewertet werden XML-Zeichen (bzw. deren Unicode-Codepoints). Einfacher ausgedrückt: Es werden auch Zeichen, die sich aus Surrogatpärchen zusammensetzen, als ein Zeichen gewertet.

Achtung – Indexziffern für Strings in XSLT beginnen bei 1:
Die Indexziffern für Zeichen in Strings beginnen in XSLT mit 1, nicht mit 0, wie beispielsweise in Java, C oder JavaScript!

Beispiele:

Anmerkung: Führende oder folgende Leerzeichen im Ergebnisstring sind in der folgenden Tabelle durch den Unterstrich verdeutlicht!

Funktionsaufruf Ergebnis

fn:substring('Ein Teststring', 1)

Ein Teststring

fn:substring('Ein Teststring', 1, 4)

Ein_

fn:substring('Ein Teststring', 1, 3)

Ein

fn:substring('Ein Teststring', 0, 3)

Ei

fn:substring('Ein Teststring', -3, 5)

E

fn:substring('Ein Teststring', 20, 5)

"" (keine Ausgabe!)

fn:substring('Ein Teststring', 1, -4)

"" (keine Ausgabe!)

fn:substring('Ein Teststring', 4)

_Teststring

fn:substring('Ein Teststring', 5.6, 3.2)

est

fn:substring('Ein Teststring', NaN)

"" (keine Ausgabe!)

fn:substring('Ein Teststring', NaN, 5)

"" (keine Ausgabe!)

fn:substring('Ein Teststring', 5, NaN)

"" (keine Ausgabe!)

fn:substring( 'Ein Teststring', -50, INF)

Ein Teststring

fn:substring( 'Ein Teststring', -INF, INF)

"" (keine Ausgabe!)

Tabelle: Funktionsaufruf von fn:substring(). 

Erläuterung zu den Beispielen:

Die Funktionslogik für die Ermittlung des Teilstrings schlägt ein Zeichen mit Index $p des Eingabestrings dann dem Ergebnisstring zu, wenn seine Position im String folgende Bedingung erfüllt: 

fn:round($startindex) 
<= $p 
fn:round($startindex) + fn:round($laenge)

Sind die übergebenen Zahlenwerte für Index und Länge keine ganzen Zahlen (siehe Beispiel 5), so werden sie gerundet.

Aus substring('Ein Teststring', 5.6, 3.2)

resultiert daher durch Rundung

substring('Ein Teststring', 6, 3).

Ist der als Startindex übergebene Wert gleich 0 oder kleiner (die Position des ersten Zeichens ist 1), so wird ein Substring ab dieser virtuellen Position generiert: fn:substring('Ein Teststring', -3, 5) ergibt 'E', da keine Zeichen mit Index -3, -2, -1 und 0 existieren. Das fünfte Zeichen ab einschließlich der virtuellen Startposition ist daher das Zeichen mit der Indexziffer 1.

Ist die Länge des zu extrahierenden Substrings zu klein gegenüber dem absoluten Wert des negativen Startindexes, so wird folgerichtig der leere String zurückgegeben: fn:substring('Ein Teststring', -10, 5) ergibt ''.

Wird als Startindex der Wert NaN übergeben (Beispiel 6), so wird gleichfalls der leere String ausgegeben: substring('Ein Teststring', NaN). (Aus der Funkti­onslogik, die dies mit NaN <= $p < NaN abbildet, ergibt sich, dass kein Zei­chen des Strings diese Bedingung erfüllen kann.)

Der leere String wird ebenfalls ausgegeben, wenn sowohl das zweite als auch das dritte Argument übergeben wird und eines davon oder beide NaN sind (Beispiele 7 und 8). Dies beruht darauf, dass NaN als Wert als ungleich zu jeder anderen Zahl gilt, die Summenbildung (rechter Ausdruck der Funktionslogik) aus gerundetem Startindex und gerundeter Länge und ein anschließender Vergleich zur Auswahl des Substrings daher nicht mög­lich sind.

Eine ähnliche Situation ergibt sich, wenn -INF als untere und +INF als obere Grenze übergeben werden – es wird nicht der gesamte String ausgegeben (wie vielleicht erwartet), sondern der leere String, da die rechte Seite (-INF + INF) des obigen Ausdrucks per Definition NaN ergibt.

Funktionsdefinition:

XPath 1.0:

substring(string, number, number?) => string

XPath 2.0:

fn:substring($sourceString as xs:string?, 
             $startingLoc as xs:double?) as xs:string?

fn:substring($sourceString as xs:string?,
             $startingLoc as xs:double?, 
             $length as xs:double?) as xs:string?

   

<< zurück vor >>
Tipp der data2type-Redaktion:
Zum Thema XSLT bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © Galileo Press, Bonn 2008
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "XSLT 2.0 & XPath 2.0 ― Das umfassende Handbuch" denselben Bestimmungen wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


Galileo Press, Rheinwerkallee 4, 53227 Bonn