fn:subsequence - XPath XQuery Reference

Find a function

XPath/XQuery subsequence function

Summary

Returns the contiguous sequence of items in the value of $sourceSeq beginning at the position indicated by the value of $startingLoc and continuing for the number of items indicated by the value of $length.

Signatures

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

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

In the two-argument case, returns:

$sourceSeq[fn:round($startingLoc) le position()]

In the three-argument case, returns:

$sourceSeq[fn:round($startingLoc) le position() 
         and position() lt fn:round($startingLoc) + fn:round($length)]

let $seq := ("item1", "item2", "item3", "item4", "item5")

The expression fn:subsequence($seq, 4) returns ("item4", "item5").

The expression fn:subsequence($seq, 3, 2) returns ("item3", "item4").

The first item of a sequence is located at position 1, not position 0.

If $sourceSeq is the empty sequence, the empty sequence is returned.

In the two-argument case, the function returns a sequence comprising those items of $sourceSeq whose index position (counting from one) is greater than or equal to the value of $startingLoc (rounded to an integer). No error occurs if $startingLoc is zero or negative.

In the three-argument case, The function returns a sequence comprising those items of $sourceSeq whose index position (counting from one) is greater than or equal to the value of $startingLoc (rounded to an integer), and less than the sum of $startingLoc and $length (both rounded to integers). No error occurs if $startingLoc is zero or negative, or if $startingLoc plus $length exceeds the number of items in the sequence, or if $length is negative.

As a consequence of the general rules, if $startingLoc is -INF and $length is +INF, then fn:round($startingLoc) + fn:round($length) is NaN; since position() lt NaN is always false, the result is an empty sequence.

The reason the function accepts arguments of type xs:double is that many computations on untyped data return an xs:double result; and the reason for the rounding rules is to compensate for any imprecision in these floating-point computations.