array:subarray

Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.

Signatures

array:subarray(
    $array as array(*), 
    $start as xs:integer
) as array(*)

array:subarray(
    $array as array(*), 
    $start as xs:integer, 
    $length as xs:integer
) as array(*)

Properties

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

Rules

Except in error cases, the two-argument version of the function returns the same result as the three-argument version when called with $length equal to the value of array:size($array) - $start + 1.

The result of the three-argument version of the function is given by the expression array:join( ($start to $start + $length - 1) ! [$array(.)] )

Error Conditions

A dynamic error is raised [ERRFOAY0001] if $start is less than one or greater than array:size($array) + 1.

For the three-argument version of the function:

A dynamic error is raised [ERRFOAY0002] if $length is less than zero.
A dynamic error is raised [ERRFOAY0001] if $start + $length is greater than array:size($array) + 1.

Notes

The value of $start can be equal to array:size($array) + 1 provided that $length is either equal to zero or omitted. In this case the result will be an empty array.

Examples

The expression array:subarray(["a", "b", "c", "d"], 2) returns ["b", "c", "d"].

The expression array:subarray(["a", "b", "c", "d"], 5) returns [ ].

The expression array:subarray(["a", "b", "c", "d"], 2, 0) returns [ ].

The expression array:subarray(["a", "b", "c", "d"], 2, 1) returns ["b"].

The expression array:subarray(["a", "b", "c", "d"], 2, 2) returns ["b", "c"].

The expression array:subarray(["a", "b", "c", "d"], 5, 0) returns [ ].

The expression array:subarray([ ], 1, 0) returns [ ].