Changes

Jump to navigation Jump to search
2,265 bytes added ,  17 February
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=
| '''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}}.
|}
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:subarray|$array as array(*), $index position as xs:integer|array(*)}}<br/>{{Func|array:subarray|$array as array(*), $index 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'''
| Constructs Returns a new array with with copy of {{Code|$lengtharray}} members of with {{Code|$arraymember}} beginning from replaced at the specified {{Code|$indexposition}}.Equivalent to <br/code>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 => array:sizeremove($position) => array) :insert- before($index + 1}}position, $member)</code>.
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: {{Code|$indexposition}} is less than one, or if not in the range {{Code|$index + $length1}} is greater than to {{Code|array:size($array) + 1}}.<br/>{{Error|FOAY0002|#Errors}}: {{Code|$length}} is less than zeroinclusive.
|-
| '''Examples'''
|
* <code>array:appendput(['member1'"a", "b", "c"], 'member2'2, "d")</code> returns the array {{Code|["member1a", "d", "member2c"]}}.
|}
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:remove|$array as array(*), $index positions as xs:integer*|array(*)}}
|-
| '''Summary'''
| Returns a copy of {{Code|$array}} without the member at the specified {{Code|$indexpositions}}.
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: {{Code|$index}} A position is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
|-
| '''Examples'''
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|array:insert-before|$array as array(*), $index position as xs:integer, $member as item()*|array(*)}}
|-
| '''Summary'''
| Returns a copy of {{Code|$array}} with one new {{Code|$member}} at the specified {{Code|$indexposition}}. Setting {{Code|$indexposition}} to the value {{Code|array:size($array) + 1}} yields the same result as {{Code|array:append($array, $insert)}}.
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: {{Code|$indexposition}} is not in the range {{Code|1}} to {{Code|array:size($array) + 1}} inclusive.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: The array is empty.
|-
| '''Examples'''
|-
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: The array is empty.
|-
| '''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}}.
|}
| '''Examples'''
|The following query returns the array {{Code|[2, 3, 4, 5, 6]}}:
 <pre classsyntaxhighlight lang="brush:xquery">
array:for-each(
array { 1 to 5 },
function($i) { $i + 1}
)
</presyntaxhighlight>
|}
|-
| '''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]}}:
<pre classsyntaxhighlight lang="brush:xquery">
array:filter(
array { 0, 1, -2, 3, -4 },
function($i) { $i > 0 }
)
</presyntaxhighlight>
|}
| '''Examples'''
|The following query returns {{Code|55}} (the sum of the integers 1 to 10):
<pre classsyntaxhighlight lang="brush:xquery">
array:fold-left(
array { 1 to 10 },
function($a, $b) { $a + $b }
)
</presyntaxhighlight>
|}
| '''Examples'''
|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:
<pre classsyntaxhighlight lang="brush:xquery">
array {
array:fold-right(
)
}
</presyntaxhighlight>
|}
| '''Examples'''
|The following query returns the array {{Code|[5, 7, 9]}}:
<pre classsyntaxhighlight lang="brush:xquery">
array:for-each-pair(
array { 1 to 3 },
function($a + $b) { $a + $b }
)
</presyntaxhighlight>
|}
==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: [[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)
Introduced with Version 8.0.
 
[[Category:XQuery]]
administrator, Bureaucrats, editor, Interface administrators, reviewer, Administrators
400

edits

Navigation menu