Changes

This [[Module Library|XQuery Module]] contains functions for manipulating arrays, which will officially be has been introduced with [[XQuery 3.1#Arrays|XQuery 3.1]].<br/>Please note that the functions are subject to change until the specification has reached its final stage.

All functions and errors in this module are assigned to the {{Code|<code><nowiki>http://www.w3.org/2005/xpath-functions/array}} </nowiki></code> namespace, which is statically bound to the {{Code|array}} prefix.<br/>

| Returns the number of members in the supplied {{Code|$array}}. Note that because an array is an item, the {{Code|fn:count}} function when applied to an array always returns {{Code|1}}.

|{{Func|array:append|$array as array(*), $insert member as item()*|array(*)}}

| Adds one member at the end Returns a copy of the array. The result is an array whose size is {{Code|array:size($array) + 1}}, in which all members in positions {{Code|1}} to with a new {{Code|array:size($array)}} are the same as the members in the corresponding position of $array, and the member in position {{Code|array:size($array) + 1}} is {{Code|$insert}}attached.

|{{Func|array:subarray|$array as array(*), $start position as xs:integer|array(*)}}<br/>{{Func|array:subarray|$array as array(*), $start position as xs:integer, $length as xs:integer|array(*)}}|-| '''Summary'''| Constructs a new array with with {{Code|$length}} members of {{Code|$array}} beginning from the specified {{Code|$position}}.<br/>The two-argument version of the function returns the same result as the three-argument version when called with {{Code|$length}} equal to the value of {{Code|array:size($array) - $position + 1}}.|-| '''Errors'''|{{Error|FOAY0001|#Errors}} {{Code|$position}} is less than one, or if {{Code|$position + $length}} is greater than {{Code|array:size($array) + 1}}.<br/>{{Error|FOAY0002|#Errors}} {{Code|$length}} is less than zero.|-| '''Examples'''|* <code>array:subarray(["a", "b", "c"], 2)</code> returns the array {{Code|["b", "c"]}}.|} ==array:put== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:put|$array as array(*), $position as xs:integer, $member as item()*|array(*)}}

| Gets an array containing all members from Returns a supplied copy of {{Code|$array starting at a supplied position, up to a specified length.<br/>The two-argument version of the function returns the same result as the three-argument version when called }} with {{Code|$lengthmember}} equal to replaced at the value of specified {{Code|$position}}. Equivalent to <code>$array => array:sizeremove($position) => array) :insert- before($position, $start + 1}}member)</code>.

|{{Error|FOAY0001|#Errors}}: {{Code|$startposition}} is less than one, or if not in the range {{Code|$start + $length1}} is greater than to {{Code|array:size($array) + 1}}.<br/>{{Error|FOAY0002|#Errors}}: {{Code|$length}} is less than zeroinclusive.

* <code>array:appendput(['member1'"a", "b", "c"], 'member2'2, "d")</code> returns the array {{Code|["member1a", "d", "member2c"]}}.

|{{Func|array:remove|$array as array(*), $index positions as xs:integer*|array(*)}}

| Constructs Returns a new copy of {{Code|$array }} without the member at the specified {{Code|$indexpositions}}.

|{{Error|FOAY0001|#Errors}}: {{Code|$index}} A position is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.

|{{Func|array:insert-before|$array as array(*), $index position as xs:integer, $insert member as item()*|array(*)}}

| Constructs Returns a new copy of {{Code|$array by adding }} with one new {{Code|$member }} at a the specified {{Code|$position}}. Setting {{Code|$indexposition}} to the value {{Code|array:size($array) + 1}} delivers yields the same result as {{Code|array:append($array, $insert)}}.

|{{Error|FOAY0001|#Errors}}: {{Code|$indexposition}} is not in the range {{Code|1}} to {{Code|array:size($array) + 1}} inclusive.

|{{Error|FOAY0001|#Errors}}: The array is empty.

==array:serializetail== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:tail|$array as array(*)|array(*)}}|-| '''Summary'''| Returns a new array with all members except the first from {{Code|$array}}. This function is equivalent to the expression {{Code|array:remove($array, 1)}}.|-| '''Errors'''|{{Error|FOAY0001|#Errors}} The array is empty.|-| '''Examples'''|* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.|} ==array:reverse== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:reverse|$array as array(*)|array(*)}}|-| '''Summary'''| Returns a new array with all members of {{Code|$array}} in reverse order.|-| '''Examples'''|* <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}.|} ==array:join== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:join|$arrays as array(*)*|array(*)}}|-| '''Summary'''| Concatenates the contents of several {{Code|$arrays}} into a single array.|-| '''Examples'''|* <code>array:join(())</code> returns the array {{Code|[]}}.* <code>array:join((1 to 3) ! array { . })</code> returns the array {{Code|[1, 2, 3]}}.|} ==array:flatten== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:flatten|$items as item()*|item()*}}|-| '''Summary'''| Recursively flattens all arrays that occur in the supplied {{Code|$items}}.|-| '''Examples'''|* <code>array:flatten(["a","b"])</code> returns the sequence {{Code|"a", "b"}}.* <code>array:flatten([1,[2,3],4]])</code> returns the sequence {{Code|1, 2, 3, 4}}.|} ==array:for-each== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:for-each|$array as array(*), $function as function(item()*) as item()*|array(*)}}|-| '''Summary'''| Returns a new array, in which each member is computed by applying {{Code|$function}} to the corresponding member of {{Code|$array}}.|-| '''Examples'''|The following query returns the array {{Code|[2, 3, 4, 5, 6]}}: <syntaxhighlight lang="xquery">array:for-each( array { 1 to 5 }, function($i) { $i + 1})</syntaxhighlight>|} ==array:filter== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:filter|$array as array(*), $function as function(item()*) as xs:boolean|array(*)}}|-| '''Summary'''| Returns a new array with those members of {{Code|$array}} for which {{Code|$function}} returns {{Code|true}}.|-| '''Examples'''|The following query returns the array {{Code|[0, 1, 3]}}:<syntaxhighlight lang="xquery">array:filter( array { 0, 1, -2, 3, -4 }, function($i) { $i > 0 })</syntaxhighlight>|} ==array:fold-left== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:fold-left|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}|-| '''Summary'''| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from left to right and using {{Code|$zero}} as first argument.|-| '''Examples'''|The following query returns {{Code|55}} (the sum of the integers 1 to 10):<syntaxhighlight lang="xquery">array:fold-left( array { 1 to 10 }, 0, function($a, $b) { $a + $b })</syntaxhighlight>|} ==array:fold-right== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:fold-right|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}|-| '''Summary'''| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from right to left and using {{Code|$zero}} as first argument.|-| '''Examples'''|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:<syntaxhighlight lang="xquery">array { array:fold-right( array { 1 to 5 }, (), function($a, $b) { $b, $a } )}</syntaxhighlight>|} ==array:for-each-pair==

|{{Func|maparray:serializefor-each-pair|$input array1 as maparray(*), $array2 as array(*), $function as function(item()*) as item()*|xs:stringarray(*)}}<br/>

| This Returns a new array obtained by evaluating the supplied {{Code|$function is specific to BaseX}} for each pair of members at the same position in {{Code|$array1}} and {{Code|$array2}}. It |-| '''Examples'''|The following query returns the array {{Code|[5, 7, 9]}}:<syntaxhighlight lang="xquery">array:for-each-pair( array { 1 to 3 }, array { 4 to 6 }, function($a + $b) { $a + $b })</syntaxhighlight>|} ==array:sort== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:sort|$array as array(*)|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string representation of the ?|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*|array(*)}}<br/>|-| '''Summary'''| Returns a new array with sorted {{Code|$array}} members, using an optional {{Code|$collation}}. If a {{Code|$key}} function is supplied , it will be applied on all arraymembers. The purpose items of this function is to get an insight into the structure resulting values will be sorted using the semantics of an array item; it cannot necessarily be used for reconstructing the original array{{Code|lt}} expression.

* <code>array:serializesort(array { reverse(1 to 3) })</code> returns <code>[ 1, 2, 3]</code>* <code>array:sort([3,-2, 31], (), 4 to 6 ]abs#1)</code> returns <code>[1, -2, 3]</code>* <code>array:sort([1,2, 3], (), function(4$x) { -$x })</code> returns <code>[3, 52, 61]</code>* <code>array:sort((1,'a'))]</code>.returns an error (strings and integers cannot be compared)

=Changelog= ;Version 8.6* Updated: [[Category#array:put|array:XQueryput]]collation argument was inserted between first and second argument.

=Changelog=;Version 8.5* Added: [[#array:put|array:put]] ;Version 8.4* Removed: array:serialize (use fn:serialize instead)