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]].
=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(*), $member as item()*|array(*)}}
|-
| '''Summary'''
| Returns a copy of {{Code|$array}} with a new {{Code|$member}} attached.
|-
| '''Examples'''
|
* <code>array:append([], 'member1')</code> returns the array {{Code|["member1"]}}.
|}
==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: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:appendfilter|$input array as array(*), $insert function as function(item()*) as xs:boolean|array(*)}}
|-
| '''Summary'''
| Adds one member at the end Returns a new array with those members of the array. The result is an array whose size is {{Code|array:size($array) + 1}}, in for which all members in positions {{Code|1}} to {{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) + 1function}} is returns {{Code|$inserttrue}}.
|-
| '''Examples'''
|* <code>array:append([], 'member1')</code> The following query returns the array {{Code|[0, 1, 3]}}:<syntaxhighlight lang="member1xquery"]>array:filter( array { 0, 1, -2, 3, -4 }, function($i) { $i > 0 }.)</syntaxhighlight>
|}
==array:serializefold-left==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|maparray:serializefold-left|$input array as maparray(*), $zero as item()*, $function as function(item()*, item()*) as item()*|xs:stringitem()*}}<br/>
|-
| '''Summary'''
| This Evaluates the supplied {{Code|$function is specific }} cumulatively on successive members of the supplied {{Code|$array}} from left to BaseXright and using {{Code|$zero}} as first argument. It |-| '''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 string representation + $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 purpose of this function 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 get an insight into 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 structure supplied {{Code|$function}} for each pair of an 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 cannot necessarily will be applied on all array members. The items of the resulting values will be used for reconstructing sorted using the semantics of 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.
