401
edits
Changes
Jump to navigation
Jump to search
* <code>array:size([1 to 10])</code> returns {{Code|10}}.
[[Category:XQuery]]=Errors= {| class="wikitable" width="100%"! width="110"|Code|Description|-|{{Code|FOAY0001}}|The specified index extends beyonds the bounds of an array.|-|{{Code|FOAY0002}}|The specified length is less than zero.|}
[[Category:XQuery]]
no edit summary
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.
=Conventions=
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/>
=Functions=
==array:size==
{| width='100%'
| width='120' | '''Signatures'''
|-
| '''Summary'''
| 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}}.
|-
| '''Examples'''
|
* <code>array:size(array { 1 to 10 })</code> returns {{Code|10}}.
* <code>array:size([1 to 10])</code> returns {{Code|1}}, because the array contains a single sequence with 10 integers.
|}
==array:get==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:get|$array as array(*), $position as xs:integer|item()*}}
|-
| '''Summary'''
| Returns the {{Code|$array}} member at the specified {{Code|$position}}.
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
|-
| '''Examples'''
|
* <code>array:get(array { reverse(1 to 5) }, 5)</code> returns the value {{Code|1}}.
|}
==array:append==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:append|$array as array(*), $insert member as item()*|array(*)}}
|-
| '''Summary'''
| 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.
|-
| '''Examples'''
==array:subarray==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:subarray|$array as array(*), $position as xs:integer|array(*)}}<br/>{{Func|array:subarray|$array as array(*), $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(*)}}
|-
| '''Summary'''
| Returns a copy of {{Code|$array}} with {{Code|$member}} replaced at the specified {{Code|$position}}. Equivalent to <code>$array => array:remove($position) => array:insert-before($position, $member)</code>.
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
|-
| '''Examples'''
|
* <code>array:put(["a", "b", "c"], 2, "d")</code> returns the array {{Code|["a", "d", "c"]}}.
|}
==array:remove==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:remove|$array as array(*), $positions as xs:integer*|array(*)}}
|-
| '''Summary'''
| Returns a copy of {{Code|$array}} without the member at the specified {{Code|$positions}}.
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}} A position is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
|-
| '''Examples'''
|
* <code>array:append(["a"], 1)</code> returns the array {{Code|[]}}.
|}
==array:insert-before==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:insert-before|$array as array(*), $position as xs:integer, $member as item()*|array(*)}}
|-
| '''Summary'''
| Returns a copy of {{Code|$array}} with one new {{Code|$member}} at the specified {{Code|$position}}. Setting {{Code|$position}} to the value {{Code|array:size($array) + 1}} yields the same result as {{Code|array:append($array, $insert)}}.
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array) + 1}} inclusive.
|-
| '''Examples'''
|
* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.
|}
==array:head==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:subarrayhead|$array as array(*), $start as xs:integer|array(*)}}<br/>{{Func|array:subarray|$array as arrayitem(*), $start as xs:integer, $length as xs:integer|array(*)}}
|-
| '''Summary'''
| Gets an Returns the first member of {{Code|$array containing all members from a supplied array starting at a supplied position, up to a specified length}}.<br/>The two-argument version of the This function returns the same result as the three-argument version when called with $length equal is equivalent to the value of expression {{Code|$array:size($array1) }}.|- $start + 1| '''Errors'''|{{Error|FOAY0001|#Errors}}The array is empty.
|-
| '''Examples'''
|
* <code>array:appendhead(["a", "b"])</code> returns {{Code|"a"}}.* <code>array:head([["a", "b"], ["c", "d"]])</code> returns the array {{Code|["a", "b"]}}.|} ==array:tail== {| width='member1100%'| 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|["member1b", "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== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:for-each-pair|$array1 as array(*), $array2 as array(*), $function as function(item()*) as item()*|array(*)}}|-| '''Summary'''| Returns a new array obtained by evaluating the supplied {{Code|$function}} for each pair of members at the same position in {{Code|$array1}} and {{Code|$array2}}.|-| '''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:serializesort==
{| width='100%'
| width='120' | '''Signatures'''
|{{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/>
|-
| '''Summary'''
| 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.
|-
| '''Examples'''
|
* <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:put|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)
Introduced with Version 8.0.
