Latest revision as of 18:35, 1 December 2023

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

Conventions[edit]

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[edit]

array:append[edit]

Signature	array:append( $array as array(), $member as item() ) as array(*)
Summary	Returns a copy of `$array` with `$member` attached.
Examples	`array:append([], 'member1')` returns the array `["member1"]`.

array:build[edit]

Signature	array:build( $input as item(), $action as function(item()) as item() := fn:identity#1 ) as array(*)
Summary	Returns an `$array` obtained by evaluating the supplied function `$action` once for each item in the `$input` sequence.
Examples	`array:build(1 to 5)` returns `[1,2,3,4,5]` `array:build(1 to 5, function { 2 * . })` returns `[2,4,6,8,10]` `array:build(1 to 5, function { 1 to . })` returns `[1,(1,2),(1,2,3),(1,2,3,4),(1,2,3,4,5)]` `array:build(1 to 5, function { array { 1 to . } })` returns `[[1],[1,2],[1,2,3],[1,2,3,4],[1,2,3,4,5]]` `array:build(("red", "green", "blue"), characters#1)` returns `[("r","e","d"),("g","r","e","e","n"),("b","l","u","e")]`

array:empty[edit]

Signature	array:empty( $array as array(*) ) as xs:boolean
Summary	Returns `true` if the supplied `$array` contains no members.
Examples	`array:empty(["a", "b", "c"])` returns `false()` `array:empty([])` returns `true()` `array:empty([[]])` returns `false()` `array:empty([()])` returns `false()`

array:exists[edit]

Signature	array:exists( $array as array(*) ) as xs:boolean
Summary	Returns `true` if the supplied `$array` contains one or more members.
Examples	`array:exists(["a", "b", "c"])` returns `true()` `array:exists([])` returns `false()` `array:exists([[]])` returns `true()` `array:exists([()])` returns `true()`

array:filter[edit]

Signature	array:filter( $array as array(), $predicate as function(item()) as xs:boolean ) as array(*)
Summary	Returns a new array with those members of `$array` for which `$predicate` 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:flatten[edit]

Signature	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:fold-left[edit]

Signature	array:fold-left( $array as array(), $zero as item(), $action as function(item(), item()) as item()* ) as item()*
Summary	Evaluates the supplied `$action` cumulatively on successive members of the supplied `$array` from left to right, and uses `$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[edit]

Signature	array:fold-right( $array as array(), $zero as item(), $action as function(item(), item()) as item()* ) as item()*
Summary	Evaluates the supplied `$action` cumulatively on successive members of the supplied `$array` from right to left, and uses `$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:foot[edit]

Signature	array:foot( $array as array() ) as item()
Summary	Returns the last member of an array, that is `$array(array:size($array))`.
Examples	`array:foot([5, 6, 7, 8])` returns `8` `array:foot([["a", "b"], ["c", "d"]])` returns `["c","d"]` `array:foot([("a", "b"), ("c", "d")])` returns 2 results `"c"` and `"d"`

array:for-each[edit]

Signature	array:for-each( $array as array(), $action as function(item()) as item()* ) as array(*)
Summary	Returns a new array, in which each member is computed by applying `$action` 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:for-each-pair[edit]

Signature	array:for-each-pair( $array1 as array(), $array2 as array(), $action as function(item()) as item() ) as array(*)
Summary	Returns a new array obtained by evaluating the supplied `$action` 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:get[edit]

Signature	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:head[edit]

Signature	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:index-where[edit]

Signature

array:index-where(
  $array	as array(*),	
  $predicate	as function(item()*, xs:integer) as xs:boolean	
) as xs:integer*

Summary Returns the position in an input $array of members that match a supplied $predicate.

Examples

array:index-where([0, (), 4, 9], boolean#1) returns ()
array:index-where([0, (), 4, 9], boolean#1) returns (3, 4)
array:index-where( array { 1 to 10 }, function {. mod 2 = 0 } ) returns (2, 4, 6, 8, 10)

array:index-where(
  [ "January", "February", "March", "April",
    "May", "June", "July", "August", "September",
    "October", "November", "December" ],
  contains(?, "r")
)

returns (1, 2, 3, 4, 9, 10, 11, 12)

array:index-where(
  [(1, 2, 3), (4, 5, 6), (7, 8)],
  function($m) { count($m) = 3 }
)

returns (1, 2)

array:index-where(
  [ 1, 8, 2, 7, 3 ],
  fn($member, $pos) { $member < 5 and $pos > 2 }
)

returns (3, 5)

array:insert-before[edit]

Signature	array:insert-before( $array as array(), $position as xs:integer, $member as item() ) as array(*)
Summary	Returns an array containing all the members of the supplied `$array`, with one additional `$member` at a specified `$position`.
Examples	array:insert-before( ["a", "b", "c", "d"], 3, ("x", "y") ) returns `["a", "b", ("x", "y"), "c", "d"]` array:insert-before( ["a", "b", "c", "d"], 5, ("x", "y") ) returns `["a", "b", "c", "d", ("x", "y")]` array:insert-before( ["a", "b", "c", "d"], 3, ["x", "y"] ) returns `["a", "b", ["x", "y"], "c", "d"]`

array:join[edit]

Signature	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:join((["a", "b"], ["c", "d"]))` returns the array `["a", "b", "c", "d"]`. `array:join((["a", "b"], ["c", "d"], [ ]))` returns the array `["a", "b", "c", "d"]`. `array:join((["a", "b"], ["c", "d"], "e", "f"))` returns the array `["a", "b", "c", "d", ["e", "f"]]`.

array:members[edit]

Signature	array:members( $array as array() ) as record(value as item())*
Summary	Delivers the contents of an `$array` as a sequence of value records.
Note	This function is the inverse of array:of-members.
Examples	`array:members([])` returns `()`. `array:members([1 to 5])?value` returns `(1, 2, 3, 4, 5)`. `array:members([(1,1), (2,4), (3,9), (4,16), (5,25)]) ! sum(?value)` returns `(2, 6, 12, 20, 30)`. let $array := [ "any array" ] return deep-equal( $array, array:of-members(array:members($array)) ) returns `true()`

array:of-members[edit]

Signature	array:of-members( $input as record(value as item()) ) as array(*)
Summary	Constructs an array from the contents of an `$input` sequence of value records.
Note	This function is the inverse of array:members.
Examples	`array:of-members(())` returns `[]`. `array:of-members(map { 'value': (1 to 5) })` returns `[(1, 2, 3, 4, 5)]`. `array:of-members((1 to 5) ! map { 'value': . })` returns `[1, 2, 3, 4, 5]`. `array:of-members((1 to 5) ! map { 'value': (., .*.) })` returns `[(1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]`.

array:put[edit]

Signature	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[edit]

Signature	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:size[edit]

Signature	array:size( $array 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:subarray[edit]

Signature	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:tail[edit]

Signature	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[edit]

Signature	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:sort[edit]

Signature	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[edit]

Code	Description
`FOAY0001`	The specified index extends beyonds the bounds of an array.
`FOAY0002`	The specified length is less than zero.

Changelog[edit]

Version 11.0

Added: array:build
Added: array:foot
Added: array:members
Added: array:of-members

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.

@@ Line 161: / Line 161: @@
 | '''Examples'''
 |The following query returns the array {{Code|[0, 1, 3]}}:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 array:filter(
    array { 0, 1, -2, 3, -4 },
@@ Line 201: / Line 201: @@
 | '''Examples'''
 |The following query returns {{Code|55}} (the sum of the integers 1 to 10):
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 array:fold-left(
    array { 1 to 10 },
@@ Line 225: / Line 225: @@
 | '''Examples'''
 |The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 array {
    array:fold-right(
@@ Line 286: / Line 286: @@
 |The following query returns the array {{Code|[2, 3, 4, 5, 6]}}:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 array:for-each(
    array { 1 to 5 },
@@ Line 309: / Line 309: @@
 | '''Examples'''
 |The following query returns the array {{Code|[5, 7, 9]}}:
-<syntaxhighlight lang="xquery">
+<pre lang='xquery'>
 array:for-each-pair(
    array { 1 to 3 },

Difference between revisions of "Array Module"