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.

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

==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-member==

|{{Func|array:for-each-member|$array as array(*), $function as function(item()*) as item()*|array(*)}}

array:for-each-member(

| Returns a new array with those members of {{Code|$array}} for which {{Code|$function}} returns {{Code|true}}.

|{{Func|array:fold-left|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}

| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from left to rightand using {{Code|$zero}} as first argument.|-| '''Examples'''|The following query returns {{Code|55}} (the sum of the integers 1 to 10):<pre class="brush:xquery">array:fold-left( array { 1 to 10 }, 0, function($a, $b) { $a + $b })

|{{Func|array:fold-leftright|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}

| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from right to leftand using {{Code|$zero}} as first argument.|-| '''Examples'''|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:<pre class="brush:xquery">array { array:fold-right( array { 1 to 5 }, (), function($a, $b) { $b, $a } )}

==array:serializesort==

|{{Func|maparray:serializesort|$input array as maparray(*)|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string?|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*|array(*)}}<br/>

| This Returns a new array with sorted {{Code|$array}} members, using an optional {{Code|$collation}}. If a {{Code|$key}} function is specific to BaseX. It returns a string representation of the 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: [[#array:sort|array:put]] collation argument was inserted between first and second argument. ;Version 8.5* Added: [[#array:put|array:put]] ;Version 8.4* Removed: array:serialize (use fn:serialize instead)