fn:string

(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: Typkonvertierung

Herkunft: XPath 1.0

Rückgabewert: Ein String xs:string, abhängig von der Art des übergebenen Arguments.

Aufruf/Argumente:

fn:string($eingabesequenz)

$eingabesequenz:
Optional. Das Argument ist eine Sequenz aus einem oder mehr Items beliebigen Datentyps, die in einen String umgewandelt werden soll, wobei aber nur das erste Item berücksichtigt wird. Wird die leere Sequenz übergeben, so gibt die Funktion einen leeren String zurück. Wird dagegen kein Argument übergeben, so wird der Stringwert des Kontext Nodes zurückgege­ben.

Verwendungszweck:

Alle Eingangsdatentypen können mittels fn:string() in Strings umgewandelt werden. Da XPath 2.0 keine implizite Typumwandlung kennt, muss diese für Eingangs­werte bestimmter Funktionen gegebenenfalls, um Typfehler zu vermeiden, mit fn:string() oder (für einzelne atomare Werte) durch die Castingfunktion cast as xs:string explizit vorgenommen werden, falls für die Weiterverarbeitung ein String xs:string benötigt wird.

In XPath 1.0 ist diese Umwandlung häufig implizit, sie kann aber mit der Funk­tion string() ebenfalls forciert werden.

Die Funktion nimmt eine Eingabesequenz entgegen. Ist diese leer, so gibt sie einen leeren String zurück. Wird der Funktion kein Argument übergeben, so bezieht sie sich automatisch auf das Kontextitem und gibt dessen Stringwert zurück. Wurde kein Argument übergeben, ist aber das Kontextitem zum Auswertungszeitpunkt nicht definiert, entsteht ein Laufzeitfehler (err:XPDY0002).

Verhalten in XPath 2.0:

Bei expliziter Anwendung von fn:string() wird in XPath 2.0 zwischen drei Gruppen von Eingabewerten unterschieden:

Eingabewert ist (direkt) ein atomarer Wert:
Die Umwandlung eines atoma­ren Wertes in einen String ist grundsätzlich in allen Fällen möglich. Die Umwandlung eines beliebigen Wertes in einen String folgt dessen kanoni­scher Form gemäß XML Schema Part 2 »Datatypes«.

Für einen booleschen Wert xs:boolean ist die kanonische Form true bzw. false, die in die Strings 'true' und 'false' umgewandelt werden (dies gilt auch, wenn die booleschen Werte als 0 oder 1 vorliegen, was zwar erlaubt ist, aber eben nicht der kanonischen Form entspricht).

Für Zahlen (Typ numeric) bedeutet dies nichts anderes, als dass eine Zahl belie­bigen Typs in eine entsprechende Ziffernfolge (gegebenenfalls mit negativem Vorzeichen und Dezimalpunkt) umgewandelt wird. Vorangestellte positive Vorzeichen (vor der Zahl selbst und auch vor dem Exponent!) sowie führende und folgende Nullen entfallen dabei, es sei denn, diese grenzen unmittelbar an den Dezimalpunkt. In Fließkommazahlen xs:float, die einen Exponent ent­halten, wird dieser im String durch ein großes E eingeleitet. Andere Zahlen­werte werden in das entsprechende Stringliteral umgewandelt: NaN in 'NaN', INF als 'INF', -INF als '-INF' (Vorsicht – hier besteht eine Inkompatibilität zu XPath 1.0!).

Handelt es sich bei dem umzuwandelnden Wert um einen URI-String vom Typ xs:anyURI, so wird er – im Gegensatz zur Casting-Funktion für Stringwerte – ohne Escaping von enthaltenen Leer- und Sonderzeichen umgewandelt. Dies ist so geregelt, weil Leerzeichen unter bestimmten Umständen innerhalb von Fragment-Identifiern erlaubt und gewollt sind. Will man daher URI-Escaping forcieren, so muss dies mittels der Funktion fn:escape-html-uri() geschehen.

Ein QName xs:QName wird umgewandelt, als ob zunächst mittels der Funktionen fn:prefix-from-QName($QName) und fn:local-name-from-QName($QName) die Einzelkomponenten ermittelt und anschließend mit einem verbindenden Doppelpunkt verkettet würden. Das Ergebnis ist also ein String in der lexikalischen Form eines QName prefix:local-name.

Die Umwandlung von Datumswerten in einen String erfordert die Einbezie­hung von Zeitzonenangaben (explizit und implizit), sofern solche vorhanden sind. Liegt die Datums-/Zeitangabe als »Universal Time Coordinated« (UTC) vor, so wird ein Z angehängt, um dies zu verdeutlichen.

Wird ein Binärwert xs:hexBinary in einen String gewandelt, so werden die Hex­zahlen A bis F grundsätzlich mit Großbuchstaben repräsentiert.

Eingabewert ist ein Node:
Der Stringwert eines Textnodes ist sein Textin­halt, der eines Kommentars der Kommentarinhalt. Als Stringwert einer PI gilt der Datenteil der Instruktion. Der Stringwert eines Namespace-Node ist der Namespace-URI-String. Der Stringwert eines Attribut-Nodes ist der Attribut­wert, derjenige eines Document Nodes oder eines anderen Elements besteht aus den in Dokumentreihenfolge zusammengefassten Textnodes aller abstam­menden Elemente.

Eingabewert ist eine Sequenz:
Ist die Sequenz leer, so gibt fn:string() den leeren String zurück. Ist die Sequenz nicht leer, so wird das erste Item in einen String umgewandelt, je nachdem, ob es sich um einen Node oder einen atoma­ren Wert handelt. Dies erfolgt dann nach einer der beiden oben angeführten Vorgehensweisen. Die restlichen Items der Sequenz werden verworfen.

Verhalten in XPath 1.0:

Wird die Funktion string() explizit oder impli­zit in XPath 1.0 verwendet, so wandelt sie den Eingabewert wie folgt um:

Number:
NaN wird in den String "NaN" umgewandelt. Positive und nega­tive 0 werden als "0" dargestellt. Positives Unendlich wird zu "Infinity", negatives Unendlich zu "-Infinity" (Achtung: Inkompatibilität zu XPath 2.0!). Eine Ganzzahl (Integer) wird dezimal ohne führende Nullen dargestellt, eventuell mit vorangestelltem Minuszeichen, falls es sich um eine negative Zahl handelt. Das Ergebnis ist eine gültige XPath-Number. Jede andere (Dezi­mal-)Zahl wird in einen String in Dezimalform umgewandelt. Dabei steht min­destens eine Ziffer vor und hinter dem Dezimalpunkt. Im Fall einer negativen Zahl wird unmittelbar ein Minuszeichen vorangestellt. Führende Nullen wer­den verworfen, es sei denn, sie stehen direkt vor dem Dezimalpunkt. Die Zahl der Nachkommastellen ist nicht begrenzt. Das Ergebnis ist auch hier eine gül­tige XPath-Number.

Boolean:
Der Boolesche Wert false wird zum String »false«, der Boolesche Wert true zum String »true« konvertiert.

String:
Der Wert bleibt unverändert.

Node:
Die Stringumwandlung der Nodes erfolgt gattungsabhängig wie in XPath 2.0 (siehe oben).

Nodeset:
Der Stringwert eines leeren Nodesets ist der leere String. Bei einem nicht leeren Nodeset wird der Stringwert desjenigen Node ausgegeben, der in Dokumentreihenfolge als erster Node im Set steht.

Result Tree Fragment:
Stringwert eines Result Tree Fragments ist – in Doku­mentreihenfolge – die Zusammenfassung aller in ihm enthaltenen Textnodes in Richtung der Descendant-Achse. (In XPath 2.0 ist das Konzept des Result Tree Fragments abgeschafft.)

Unterschied zwischen Konstruktor xs:string() und fn:string()
In XPath 2.0 existiert für Strings zusätzlich eine Konstruktorfunk­tion xs:string(), deren Rückgabewerte sich bei gleichem Argument von demjenigen von fn:string() unterscheidet, da nicht der Stringwert des Arguments zurückgegeben wird, sondern der Stringwert des Arguments nach dessen erfolgter Atomisierung.

Beispiel – Stringwert einer Node-Sequenz:

Gelegentlich kann es praktisch sein, die Funktion fn:string() explizit aufzu­rufen, beispielsweise, wenn man statt eines Vergleichs zwischen String und Node-Sequenz zwei Strings direkt vergleichen möchte.

In dieser Beispieldatei befinden sich Bücher mit mehreren Autoren:

Es sollen in diesem Dokument solche Bücher gefunden werden, deren Haupt­autor einem vorgegebenen Autornamen entspricht. Der Hauptautor soll hier­bei stets der im Buchelement zuerst genannte Autor sein.

Folgendes führt nicht zum gewünschten Ergebnis:

In diesem Fall wird nämlich jedes Buch ausgegeben, bei dem irgendein Autor­element den Vergleichsstring enthält, also auch das zweite, dritte etc.

Mit Hilfe der Funktion fn:string() lässt sich folgender Ausdruck formulie­ren, der nur den Stringwert des ersten Autorelements berücksichtigt:

Dieser Test ist nur dann erfolgreich, wenn der String 'Anton Autor' als Name des Hauptautors im ersten Autorelement erscheint, da für eine übergebene Node-Sequenz – und genau das ist hier der Fall – der Stringwert des ersten Kno­tens zurückgegeben wird.

Funktionsdefinition:

XPath 1.0:

string(object) => string

XPath 2.0:

fn:string() as xs:string

fn:string($arg as item()?) as xs:string