XSLT and XPath function reference in alphabetical order

(Excerpt from “XSLT 2.0 & XPath 2.0” by Frank Bongers, chapter 5, translated from German)

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

fn:subsequence

Category:

Functions for sequences

Origin:

XPath 2.0

Return value:

A sequence; a subsequence of a related series of items of the input sequence in unchanged order, determined by the start index passed on and, where applicable, by the length indication.

Call/Arguments:

fn:subsequence($inputSequence?, $startIndex, $length?)

$inputSequence:

A sequence of any number of items of any type from which a subsequence shall be extracted and returned. If the input sequence is empty, the function returns the empty sequence.

$startIndex:

Obligatory. A number of xs:double type from which, by rounding according to the fn:round() function, the index position of the item is determined by which the extracted subsequence starts with.

$length:

Optional. A number of xs:double type from which, by rounding according to fn:round(), the number of the items of the subsequence is determined.

Purpose of use:

The fn:subsequence() function extracts a subsequence from an input sequence, which means an uninterrupted, related series of the items in unchanged order. The input sequence may be empty. In this case, the function always returns an empty result sequence.

Position of the start item of the subsequence:

For the determination of the subsequence, the function requires as second argument the position of the start item and, in addition, optionally the length of the sequence to be extracted from the input sequence (its item number). Both numbers must be integers. However, the function accepts any numeric types (which result, for example, from XPath expressions) and rounds, where appropriate, according to fn:round().

If the result of the rounding of the start index indication is the number 0 or lower, the subsequence starts with the firts item (position 1) of the input sequence. No error is reported. If the start index indication is higher than the number of the items in the input sequence, the empty sequence is returned.

If no third argument is passed on, which means no length indication, the subsequence is returned from and including the determined start item up to the end of the input sequence.

With indication of a subsequence length:

If there is a third argument as length indication, the number passed on is firstly rounded. The subsequence includes a number of items corresponding to the length indication, whereby the determined start item is also counted.

If the length indication exceeds the number of items remaining in the input sequence after the start item, the subsequence includes the existing items from and including the start item up to the end of the input sequence (which means the rest of the input sequence). No error is reported.

If, after rounding, the length indication is 0 or negative, the empty sequence is returned. (This is analogous to the behaviour of fn:substring() for length indications of substrings to be extracted.)

Example 1 – subsequence of a sequence:

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

results in: ('c', 'd', 'e'). The third item 'c' is the start item of the extracted subsequence. Since no length indication was passed on, all items of the input sequence from and including the third item are outputted.

Example 2 – passing on a too high index indication:

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

results in the empty sequence:(). Since the fifth item by which the subsequence shall start does not exist, the empty sequence is returned.

Example 3 – passing on a length indication:

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

results in: ('c', 'd'). The third item 'c' is, after rounding up the value passed on to 3, the start item of the subsequence to be extracted. The length indication passed on of 2 restricts the length of the subsequence to two items.

Example 4 – passing on a negative length indication:

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

results in the empty sequence: (). The third item 'c' is, as above, after rounding up the value passed on to 3, the potential start item of the subsequence to be extracted.

However, since the length indication also passed on results after rounding in a negative value, the empty sequence is returned. (No subsequence in the opposite direction is generated!)

Function definition:

XPath 1.0:

The function is not available.

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()*

   

<< back

next >>