This XQuery Module contains functions for manipulating arrays, which has been introduced with XQuery 3.1.
Conventions
All functions in this module are assigned to the http://www.w3.org/2005/xpath-functions/array
namespace, which is statically bound to the array
prefix.
Functions
array:size
Signatures
|
array:size($input as array(*)) as xs:integer
|
Summary
|
Returns the number of members in $array . Note that because an array is an item, the fn:count function when applied to an array always returns 1 .
|
Examples
|
array:size(array { 1 to 10 }) returns 10 .
array:size([1 to 10]) returns 1 , because the array contains a single sequence with 10 integers.
|
array:get
Signatures
|
array:get($array as array(*), $position as xs:integer) as item()*
|
Summary
|
Returns the $array member at the specified $position .
|
Errors
|
FOAY0001 : $position is not in the range 1 to array:size($array) inclusive.
|
Examples
|
array:get(array { reverse(1 to 5) }, 5) returns the value 1 .
|
array:append
Signatures
|
array:append($array as array(*), $member as item()*) as array(*)
|
Summary
|
Returns a copy of $array with a new $member attached.
|
Examples
|
array:append([], 'member1') returns the array ["member1"] .
|
array:subarray
Signatures
|
array:subarray($array as array(*), $position as xs:integer) as array(*)
array:subarray($array as array(*), $position as xs:integer, $length as xs:integer) as array(*)
|
Summary
|
Constructs a new array with with $length members of $array beginning from the specified $position . 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) - $position + 1 .
|
Errors
|
FOAY0001 : $position is less than one, or if $position + $length is greater than array:size($array) + 1 .
FOAY0002 : $length is less than zero.
|
Examples
|
array:subarray(["a", "b", "c"], 2) returns the array ["b", "c"] .
|
array:put
Signatures
|
array:put($array as array(*), $position as xs:integer, $member as item()*) as array(*)
|
Summary
|
Returns a copy of $array with $member replaced at the specified $position . Equivalent to $array => array:remove($position) => array:insert-before($position, $member) .
|
Errors
|
FOAY0001 : $position is not in the range 1 to array:size($array) inclusive.
|
Examples
|
array:put(["a", "b", "c"], 2, "d") returns the array ["a", "d", "c"] .
|
array:remove
Signatures
|
array:remove($array as array(*), $positions as xs:integer*) as array(*)
|
Summary
|
Returns a copy of $array without the member at the specified $positions .
|
Errors
|
FOAY0001 : A position is not in the range 1 to array:size($array) inclusive.
|
Examples
|
array:append(["a"], 1) returns the array [] .
|
array:insert-before
Signatures
|
array:insert-before($array as array(*), $position as xs:integer, $member as item()*) as array(*)
|
Summary
|
Returns a copy of $array with one new $member at the specified $position . Setting $position to the value array:size($array) + 1 yields the same result as array:append($array, $insert) .
|
Errors
|
FOAY0001 : $position is not in the range 1 to array:size($array) + 1 inclusive.
|
Examples
|
array:insert-before(["a"], 1, "b") returns the array ["b", "a"] .
|
array:head
Signatures
|
array:head($array as array(*)) as item()*
|
Summary
|
Returns the first member of $array . This function is equivalent to the expression $array(1) .
|
Errors
|
FOAY0001 : The array is empty.
|
Examples
|
array:head(["a", "b"]) returns "a" .
array:head([["a", "b"], ["c", "d"]]) returns the array ["a", "b"] .
|
array:tail
Signatures
|
array:tail($array as array(*)) as array(*)
|
Summary
|
Returns a new array with all members except the first from $array . This function is equivalent to the expression array:remove($array, 1) .
|
Errors
|
FOAY0001 : The array is empty.
|
Examples
|
array:insert-before(["a"], 1, "b") returns the array ["b", "a"] .
|
array:reverse
Signatures
|
array:reverse($array as array(*)) as array(*)
|
Summary
|
Returns a new array with all members of $array in reverse order.
|
Examples
|
array:reverse(array { 1 to 3 }) returns the array [3, 2, 1] .
|
array:join
Signatures
|
array:join($arrays as array(*)*) as array(*)
|
Summary
|
Concatenates the contents of several $arrays into a single array.
|
Examples
|
array:join(()) returns the array [] .
array:join((1 to 3) ! array { . }) returns the array [1, 2, 3] .
|
array:flatten
Signatures
|
array:flatten($items as item()*) as item()*
|
Summary
|
Recursively flattens all arrays that occur in the supplied $items .
|
Examples
|
array:flatten(["a","b"]) returns the sequence "a", "b" .
array:flatten([1,[2,3],4]]) returns the sequence 1, 2, 3, 4 .
|
array:for-each
Signatures
|
array:for-each($array as array(*), $function as function(item()*) as item()*) as array(*)
|
Summary
|
Returns a new array, in which each member is computed by applying $function to the corresponding member of $array .
|
Examples
|
The following query returns the array [2, 3, 4, 5, 6] :
array:for-each(
array { 1 to 5 },
function($i) { $i + 1}
)
|
array:filter
Signatures
|
array:filter($array as array(*), $function as function(item()*) as xs:boolean) as array(*)
|
Summary
|
Returns a new array with those members of $array for which $function returns true .
|
Examples
|
The following query returns the array [0, 1, 3] :
array:filter(
array { 0, 1, -2, 3, -4 },
function($i) { $i > 0 }
)
|
array:fold-left
Signatures
|
array:fold-left($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
|
Summary
|
Evaluates the supplied $function cumulatively on successive members of the supplied $array from left to right and using $zero as first argument.
|
Examples
|
The following query returns 55 (the sum of the integers 1 to 10):
array:fold-left(
array { 1 to 10 },
0,
function($a, $b) { $a + $b }
)
|
array:fold-right
Signatures
|
array:fold-right($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
|
Summary
|
Evaluates the supplied $function cumulatively on successive members of the supplied $array from right to left and using $zero as first argument.
|
Examples
|
The following query is equivalent to the expression array:reverse(array { 1 to 5 }) :
array {
array:fold-right(
array { 1 to 5 },
(),
function($a, $b) { $b, $a }
)
}
|
array:for-each-pair
Signatures
|
array:for-each-pair($array1 as array(*), $array2 as array(*), $function as function(item()*) as item()*) as array(*)
|
Summary
|
Returns a new array obtained by evaluating the supplied $function for each pair of members at the same position in $array1 and $array2 .
|
Examples
|
The following query returns the array [5, 7, 9] :
array:for-each-pair(
array { 1 to 3 },
array { 4 to 6 },
function($a + $b) { $a + $b }
)
|
array:sort
Signatures
|
array:sort($array as array(*)) as array(*)
array:sort($array as array(*), $collation as xs:string?) as xs:anyAtomicType*) as array(*)
array:sort($array as array(*), $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*) as array(*)
|
Summary
|
Returns a new array with sorted $array members, using an optional $collation . If a $key function is supplied, it will be applied on all array members. The items of the resulting values will be sorted using the semantics of the lt expression.
|
Examples
|
array:sort(array { reverse(1 to 3) }) returns [1, 2, 3]
array:sort([3,-2,1], (), abs#1) returns [1, -2, 3]
array:sort([1,2,3], (), function($x) { -$x }) returns [3, 2, 1]
array:sort((1,'a')) returns an error (strings and integers cannot be compared)
|
Errors
Code
|
Description
|
FOAY0001
|
The specified index extends beyonds the bounds of an array.
|
FOAY0002
|
The specified length is less than zero.
|
Changelog
- Version 8.6
- Updated: Collation argument was inserted between first and second argument.
- Version 8.5
- Version 8.4
- Removed: array:serialize (use fn:serialize instead)
Introduced with Version 8.0.