Changes

Jump to navigation Jump to search
8,828 bytes added ,  17:40, 17 February 2020
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([1 to 10])</code> returns {{Code|10}}.
* <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|$input 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:serializesubarray== {| 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|maparray:serializeinsert-before|$input array as maparray(*)|, $position as xs:stringinteger, $member as item()*|array(*)}}<br/>
|-
| '''Summary'''
| This function is specific to BaseX. It returns Returns a string representation 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 supplied same result as {{Code|array:append($array, $insert)}}. The purpose of this function |-| '''Errors'''|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to get an insight into the structure of an {{Code|array item; it cannot necessarily be used for reconstructing the original :size($array) + 1}} inclusive.
|-
| '''Examples'''
|
* <code>array:serializeinsert-before([ "a"], 1, (2, 3), 4 to 6 ]"b")</code> returns <code>the array {{Code|[1"b", (2, 3), (4, 5, 6)"a"]</code>}}.
|}
==array:head== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:head|$array as array(*)|item()*}}|-| '''Summary'''| Returns the first member of {{Code|$array}}. This function is equivalent to the expression {{Code|$array(1)}}.|-| '''Errors'''|{{Error|FOAY0001|#Errors}} The array is empty.|-| '''Examples'''|* <code>array:head(["a", "b"])</code> returns {{Code|"a"}}.* <code>array:head([["a", "b"], ["c", "d"]])</code> returns the array {{Code|["a", "b"]}}.|} ==array:tail== {| 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|[Category0, 1, 3]}}:XQuery<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:sort== {| width='100%'| width='120' | '''Signatures'''|{{Func|array:sort|$array as array(*)|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'''| 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 array members. The items of the resulting values will be sorted using the semantics of the {{Code|lt}} expression.|-| '''Examples'''|* <code>array:sort(array { reverse(1 to 3) })</code> returns <code>[1, 2, 3]</code>* <code>array:sort([3,-2,1], (), abs#1)</code> returns <code>[1, -2, 3]</code>* <code>array:sort([1,2,3], (), function($x) { -$x })</code> returns <code>[3, 2, 1]</code>* <code>array:sort((1,'a'))</code> returns an error (strings and integers cannot be compared)|} =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.|}
=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.
 
[[Category:XQuery]]
administrator, Bureaucrats, editor, Interface administrators, reviewer, Administrators
401

edits

Navigation menu