fn:subsequence

(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: Funktionen für Sequenzen

Herkunft: XPath 2.0

Rückgabewert: Eine Sequenz; eine Teilsequenz aus einer zusammenhängen­den Folge von Items der Eingabesequenz in unveränderter Reihenfolge, bestimmt durch den übergebenen Startindex und gegebenenfalls durch eine Längenangabe.

Aufruf/Argumente:

fn:subsequence($eingabesequenz?, $startindex, $laenge?)

$eingabesequenz:
Eine Sequenz aus einer beliebigen Anzahl von Items beliebigen Typs, aus der eine Teilsequenz extrahiert und zurückgegeben wer­den soll. Ist die Eingabesequenz leer, so gibt die Funktion die leere Sequenz zurück.

$startindex:
Obligatorisch. Eine Zahl vom Typ xs:double, aus der durch Rundung gemäß fn:round() die Indexposition desjenigen Items ermittelt wird, mit dem die extrahierte Teilsequenz beginnt.

$laenge:
Optional. Eine Zahl vom Typ xs:double, aus der durch Rundung gemäß fn:round() die Anzahl der Items der Teilsequenz bestimmt wird.

Verwendungszweck:

Die Funktion fn:subsequence() extrahiert eine Teilsequenz aus einer Eingabesequenz, d.h. eine lückenlose, zusammenhängende Folge deren Items in unveränderter Reihenfolge. Die Eingabeseuqenz darf dabei leer sein. In diesem Fall gibt die Funktion stets eine leere Ergebnissequenz zurück. 

Position des Startitems der Teilsequenz:

Zur Bestimmung der Teilsequenz muss der Funktion als zweites Argument obligatorisch die Position deren Starti­tems, und dazu optional auch die Länge der aus der Eingabesequenz zu extrahierenden Sequenz (also deren Itemzahl) mitgeteilt werden. Beide Zahlen müssen letztlich Ganzzahlen sein. Die Funktion akzeptiert jedoch beliebige numerische Typen (die sich z.B. aus XPath-Ausdrücken ergeben) und rundet gegebenenfalls entsprechend fn:round(). 

Ist das Ergebnis der Rundung der Startindexangabe die Zahl 0 oder kleiner, so beginnt die Teilsequenz mit dem ersten Item (Position 1) der Eingabesequenz. Es wird kein Fehler gemeldet. Liegt die Startindexangabe höher als die Zahl der Items in der Eingabesequenz, so wird die leere Sequenz zurückgegeben.

Wird kein drittes Argument, also keine Längenangabe übergeben, so wird die Teilsequenz ab einschließlich dem ermittelten Startitem bis zum Ende der Ein­gabesequenz zurückgegeben. 

Mit Angabe einer Teilsequenzlänge:

Liegt ein drittes Argument als Längenangabe vor, so wird die übergebene Zahl zunächst gerundet. Die Teilsequenz umfasst eine der Längenangabe entsprechende Anzahl von Items, wobei das ermittelte Startitem mitgezählt wird. 

Übersteigt die Längenangabe die in der Eingabesequenz nach dem Startitem verbleibende Zahl von Items, so beinhaltet die Teilsequenz die vorhandenen Items ab ein­schließlich des Startitems bis zum Ende der Eingabesequenz (also den Rest der Eingabesequenz). Es wird kein Fehler gemeldet.

Ist die Längenangabe nach Rundung gleich 0 oder negativ, so wird die leere Sequenz zurückgegeben. (Dies ist analog zum Verhalten von fn:substring() für Längenangaben von zu extrahierenden Teilstrings.)

Beispiele:

Beispiel 1 – Teilsequenz aus einer Sequenz:

fn:subsequence(('a', 'b', 'c', 'd', 'e'), 3)

ergibt ('c', 'd', 'e'). Das dritte Item 'c' bildet das Startitem der extra­hierten Teilsequenz. Da keine Längenangabe übergeben wurde, werden alle Items der Eingabesequenz ab einschließlich des dritten Items ausgegeben.

Beispiel 2 – Übergabe einer zu hohen Indexangabe:

fn:subsequence(('a', 'b', 'c', 'd'), 5)

ergibt die leere Sequenz (). Da das fünfte Item, bei dem die Teilsequenz begin­nen soll, nicht existiert, wird die leere Sequenz zurückgegeben.

Beispiel 3 – Übergabe einer Längenangabe:

fn:subsequence(('a', 'b', 'c', 'd', 'e'), 2.8, 2)

ergibt ('c', 'd'). Das dritte Item 'c' bildet nach Aufrundung des übergebe­nen Wertes auf 3 das Startitem der zu extrahierenden Teilsequenz. Die überge­bene Längenangabe von 2 beschränkt die Länge der Teilsequenz auf zwei Items.

Beispiel 4 – Übergabe einer negativen Längenangabe:

fn:subsequence(('a', 'b', 'c', 'd', 'e'), 2.8, -2.2)

ergibt die leere Sequenz (). Das dritte Item 'c' bildet wie zuvor nach Aufrun­dung des übergebenen Wertes auf 3 das potenzielle Startitem der zu extrahie­renden Teilsequenz.

Da die ebenfalls übergebene Längenangabe nach Rundung jedoch einen nega­tiven Wert ergibt, wird die leere Sequenz zurückgegeben. (Es wird nicht etwa eine Teilsequenz in umgekehrter Richtung gebildet!)

Funktionsdefinition:

XPath 1.0:

Funktion nicht verfügbar

XPath 2.0:

fn:subsequence($sourceSeq as item()*,
               $startingLoc as xs:double) as item()*

fn:subsequence($sourceSeq as item()*,
               $startingLoc as xs:double,
               $length as xs:double) as item()*

   

<< zurück

vor >>