Revision as of 18:38, 17 February 2020

This XQuery Module contains functions for manipulating arrays, which has been introduced with XQuery 3.1.

Conventions

All functions and errors 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]:

<syntaxhighlight lang="xquery"> array:for-each(

 array { 1 to 5 },
 function($i) { $i + 1}

) </syntaxhighlight>

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 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: array:put collation argument was inserted between first and second argument.

Version 8.5

Added: array:put

Version 8.4

Removed: array:serialize (use fn:serialize instead)

Introduced with Version 8.0.

Difference between revisions of "Array Module"

Revision as of 18:38, 17 February 2020

Contents