fn:insert-before

(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 neue Sequenz aus der Kopie der Eingabe­sequenz, in welche vor der bezeichneten Indexposition die als drittes Argument übergebene Sequenz eingefügt wurde.

Aufruf/Argumente:

fn:insert-before($eingabesequenz, $indexangabe, $einschubsequenz)

$eingabesequenz:
Obligatorisch. Eine Sequenz aus einer beliebigen Zahl von Items, in deren Kopie die als drittes Argument übergebene Einschubse­quenz eingefügt wird.

indexangabe:
Obligatorisch. Eine (im Prinzip positive) Ganzzahl xs:inte­ger, welche die Indexposition bezeichnet, vor der die Einschubsequenz in die Ein­gabesequenz eingefügt wird.

$einschubsequenz:
Obligatorisch. Eine Sequenz aus einer beliebigen Zahl von Items, die vor der übergebenen Indexposition in die als erstes Argument übergebene Eingabesequenz eingefügt wird.

Verwendungszweck:

Die Funktion erzeugt aus beiden ihr übergebe­nen Sequenzen eine neue Sequenz, indem sie die zweite Sequenz vor der übergebenen Indexposition in eine Kopie der als erstes Argu­ment übergebenen Sequenz einfügt.

Die Anzahl der Items der Ergebnissequenz entspricht stets der Summe der Items beider übergebener Sequenzen. Die Typen der Items der zurückgege­benen Sequenz entsprechen unverändert den Typen der korrespondierenden Items der Ein­gabesequenzen.

Die als zweites Argument übergebene Indexziffer soll eine ganze, positive Zahl sein. Ist der übergebene Wert kleiner oder gleich 0, so wird er ignoriert und statt dessen der Wert 1 angenommen. Die Items der Einschubsequenz werden in diesem Fall vor dem ersten Item der Eingabesequenz eingefügt.

Ist der übergebene Wert größer als die Zahl der Items in der Eingabesequenz des ersten Arguments, so wird der Wert ignoriert und statt dessen die Länge der Eingabesequenz +1 angenommen. Die Items der Einschubsequenz werden in diesem Fall nach dem letzten Item der Eingabesequenz angehängt (exakter ausgedrückt: vor der n+1-ten Indexnummer eingefügt, bei n Items in der Ein­gabesequenz).

Ist die erste Sequenz leer, so wird die Einschubsequenz zurückge­geben. Ist dagegen die einzufügende Sequenz leer, so wird eine Kopie der unverän­derten ersten Sequenz zurückgegeben. Sind beide Sequenzen leer, so gibt die Funktion naheliegenderweise eine leere Ergebnissequenz zurück.

Beispiele:

Beispiel 1 – Einfügen einer Sequenz:

fn:insert-before( ('a', 'b', 'c'), 
                    2, 
                   (1, 2, 3)
  )

ergibt ('a', 1, 2, 3, 'b', 'c').

Die zweite Sequenz wird vor der übergebenen Indexposition 2 in die erste ein­gefügt und die Gesamtsequenz als neue Sequenz zurückgegeben.

Beispiel 2 – Indexangabe außerhalb des erlaubten Bereichs, Version 1:

fn:insert-before( ('a', 'b', 'c'), 
                    0, 
                   (1, 2, 3)
  )

ergibt (1, 2, 3, 'a', 'b', 'c').

Die zweite Sequenz wird vor dem ersten Item der ersten Sequenz eingefügt und die Gesamtsequenz zurückgegeben. Die eigentlich übergebene Indexan­gabe von 0 wird durch 1 ersetzt.

Beispiel 3 – Indexangabe außerhalb des erlaubten Bereichs, Version 2:

fn:insert-before( ('a', 'b', 'c'), 
                    7, 
                   (1, 2, 3)
  )

ergibt ('a', 'b', 'c', 1, 2, 3).

Die zweite Sequenz wird nach dem letzten Item der ersten Sequenz eingefügt und die Gesamtsequenz zurückgegeben. Die eigentlich übergebene Indexan­gabe von 7 wird durch 4 (Länge der ersten Sequenz + 1) ersetzt.

Beispiel 4 – Alternativen zu fn:insert-before:

Sollen zwei Sequenzen $sequenz_a und $sequenz_b lediglich aneinander gehängt werden, so kann dies auch einfach mit Hilfe des Komma-Operators geschehen. Der Ausdruck

($sequenz_a, $sequenz_b)

konstruiert eine neue Sequenz, die aus den Items von $sequenz_a gefolgt von den Items von $sequenz_b besteht. Die Verwendung der Funktion fn:insert-before() ist in diesem Fall nicht erforderlich bzw. wäre unnötig kompliziert.

Funktionsdefinition:

XPath 1.0:

Funktion nicht verfügbar

XPath 2.0:

fn:insert-before($target as item()*,
                 $position as xs:integer, 
                 $inserts as item()*) as item()*

   

<< zurück

vor >>