From BaseX Documentation
(Difference between revisions)


Line 333: 
Line 333: 
   
 ;Version 8.6   ;Version 8.6 
  * Updated: Collation argument was inserted between first and second argument.  +  * Updated: [[#array:sort]] collation argument was inserted between first and second argument. 
   
 ;Version 8.5   ;Version 8.5 
Revision as of 03:07, 21 September 2018
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/xpathfunctions/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 twoargument version of the function returns the same result as the threeargument 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:insertbefore($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:insertbefore
Signatures
 array:insertbefore($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:insertbefore(["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:insertbefore(["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:foreach
Signatures
 array:foreach($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:foreach(
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:foldleft
Signatures
 array:foldleft($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:foldleft(
array { 1 to 10 },
0,
function($a, $b) { $a + $b }
)

array:foldright
Signatures
 array:foldright($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:foldright(
array { 1 to 5 },
(),
function($a, $b) { $b, $a }
)
}

array:foreachpair
Signatures
 array:foreachpair($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:foreachpair(
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:sort 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.