Difference between revisions of "Array Module"
Jump to navigation
Jump to search
(54 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains functions for manipulating arrays, which | + | This [[Module Library|XQuery Module]] contains functions for manipulating arrays, which has been introduced with [[XQuery 3.1#Arrays|XQuery 3.1]]. |
=Conventions= | =Conventions= | ||
− | All functions in this module are assigned to the | + | All functions and errors in this module are assigned to the <code><nowiki>http://www.w3.org/2005/xpath-functions/array</nowiki></code> namespace, which is statically bound to the {{Code|array}} prefix.<br/> |
=Functions= | =Functions= | ||
==array:size== | ==array:size== | ||
+ | |||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
Line 13: | Line 14: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns the number of members in | + | | Returns the number of members in {{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''' | | '''Examples''' | ||
| | | | ||
− | |||
* <code>array:size(array { 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== | ==array:append== | ||
+ | |||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|array:append|$ | + | |{{Func|array:append|$array as array(*), $member as item()*|array(*)}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | | + | | Returns a copy of {{Code|$array}} with a new {{Code|$member}} attached. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 34: | Line 53: | ||
|} | |} | ||
− | ==array: | + | ==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='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func| | + | |{{Func|array:join|$arrays as array(*)*|array(*)}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | | + | | Concatenates the contents of several {{Code|$arrays}} into a single array. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>array: | + | * <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]}}: | ||
+ | <pre class="brush:xquery"> | ||
+ | array:for-each( | ||
+ | array { 1 to 5 }, | ||
+ | function($i) { $i + 1} | ||
+ | ) | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==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]}}: | ||
+ | <pre class="brush:xquery"> | ||
+ | array:filter( | ||
+ | array { 0, 1, -2, 3, -4 }, | ||
+ | function($i) { $i > 0 } | ||
+ | ) | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==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): | ||
+ | <pre class="brush:xquery"> | ||
+ | array:fold-left( | ||
+ | array { 1 to 10 }, | ||
+ | 0, | ||
+ | function($a, $b) { $a + $b } | ||
+ | ) | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==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>: | ||
+ | <pre class="brush:xquery"> | ||
+ | array { | ||
+ | array:fold-right( | ||
+ | array { 1 to 5 }, | ||
+ | (), | ||
+ | function($a, $b) { $b, $a } | ||
+ | ) | ||
+ | } | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==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]}}: | ||
+ | <pre class="brush:xquery"> | ||
+ | array:for-each-pair( | ||
+ | array { 1 to 3 }, | ||
+ | array { 4 to 6 }, | ||
+ | function($a + $b) { $a + $b } | ||
+ | ) | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==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= | =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) | ||
Introduced with Version 8.0. | Introduced with Version 8.0. | ||
− | |||
− |
Revision as of 11:39, 27 September 2018
This XQuery Module contains functions for manipulating arrays, which has been introduced with XQuery 3.1.
Contents
- 1 Conventions
- 2 Functions
- 2.1 array:size
- 2.2 array:get
- 2.3 array:append
- 2.4 array:subarray
- 2.5 array:put
- 2.6 array:remove
- 2.7 array:insert-before
- 2.8 array:head
- 2.9 array:tail
- 2.10 array:reverse
- 2.11 array:join
- 2.12 array:flatten
- 2.13 array:for-each
- 2.14 array:filter
- 2.15 array:fold-left
- 2.16 array:fold-right
- 2.17 array:for-each-pair
- 2.18 array:sort
- 3 Errors
- 4 Changelog
Conventions
All functions and errors in this module are assigned to the http://www.w3.org/2005/xpath-functions/array
namespace, which is statically bound to the array
prefix.
Functions
array:size
Signatures | array:size($input as array(*)) as xs:integer
|
Summary | Returns the number of members in $array . Note that because an array is an item, the fn:count function when applied to an array always returns 1 .
|
Examples |
|
array:get
Signatures | array:get($array as array(*), $position as xs:integer) as item()*
|
Summary | Returns the $array member at the specified $position .
|
Errors | FOAY0001 : $position is not in the range 1 to array:size($array) inclusive.
|
Examples |
|
array:append
Signatures | array:append($array as array(*), $member as item()*) as array(*)
|
Summary | Returns a copy of $array with a new $member attached.
|
Examples |
|
array:subarray
Signatures | array:subarray($array as array(*), $position as xs:integer) as array(*) array:subarray($array as array(*), $position as xs:integer, $length as xs:integer) as array(*)
|
Summary | Constructs a new array with with $length members of $array beginning from the specified $position .The two-argument version of the function returns the same result as the three-argument version when called with $length equal to the value of array:size($array) - $position + 1 .
|
Errors | FOAY0001 : $position is less than one, or if $position + $length is greater than array:size($array) + 1 .FOAY0002 : $length is less than zero.
|
Examples |
|
array:put
Signatures | array:put($array as array(*), $position as xs:integer, $member as item()*) as array(*)
|
Summary | Returns a copy of $array with $member replaced at the specified $position . Equivalent to $array => array:remove($position) => array:insert-before($position, $member) .
|
Errors | FOAY0001 : $position is not in the range 1 to array:size($array) inclusive.
|
Examples |
|
array:remove
Signatures | array:remove($array as array(*), $positions as xs:integer*) as array(*)
|
Summary | Returns a copy of $array without the member at the specified $positions .
|
Errors | FOAY0001 : A position is not in the range 1 to array:size($array) inclusive.
|
Examples |
|
array:insert-before
Signatures | array:insert-before($array as array(*), $position as xs:integer, $member as item()*) as array(*)
|
Summary | Returns a copy of $array with one new $member at the specified $position . Setting $position to the value array:size($array) + 1 yields the same result as array:append($array, $insert) .
|
Errors | FOAY0001 : $position is not in the range 1 to array:size($array) + 1 inclusive.
|
Examples |
|
array:head
Signatures | array:head($array as array(*)) as item()*
|
Summary | Returns the first member of $array . This function is equivalent to the expression $array(1) .
|
Errors | FOAY0001 : The array is empty.
|
Examples |
|
array:tail
Signatures | array:tail($array as array(*)) as array(*)
|
Summary | Returns a new array with all members except the first from $array . This function is equivalent to the expression array:remove($array, 1) .
|
Errors | FOAY0001 : The array is empty.
|
Examples |
|
array:reverse
Signatures | array:reverse($array as array(*)) as array(*)
|
Summary | Returns a new array with all members of $array in reverse order.
|
Examples |
|
array:join
Signatures | array:join($arrays as array(*)*) as array(*)
|
Summary | Concatenates the contents of several $arrays into a single array.
|
Examples |
|
array:flatten
Signatures | array:flatten($items as item()*) as item()*
|
Summary | Recursively flattens all arrays that occur in the supplied $items .
|
Examples |
|
array:for-each
Signatures | array:for-each($array as array(*), $function as function(item()*) as item()*) as array(*)
|
Summary | Returns a new array, in which each member is computed by applying $function to the corresponding member of $array .
|
Examples | The following query returns the array [2, 3, 4, 5, 6] :
array:for-each( array { 1 to 5 }, function($i) { $i + 1} ) |
array:filter
Signatures | array:filter($array as array(*), $function as function(item()*) as xs:boolean) as array(*)
|
Summary | Returns a new array with those members of $array for which $function returns true .
|
Examples | The following query returns the array [0, 1, 3] :
array:filter( array { 0, 1, -2, 3, -4 }, function($i) { $i > 0 } ) |
array:fold-left
Signatures | array:fold-left($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
|
Summary | Evaluates the supplied $function cumulatively on successive members of the supplied $array from left to right and using $zero as first argument.
|
Examples | The following query returns 55 (the sum of the integers 1 to 10):
array:fold-left( array { 1 to 10 }, 0, function($a, $b) { $a + $b } ) |
array:fold-right
Signatures | array:fold-right($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
|
Summary | Evaluates the supplied $function cumulatively on successive members of the supplied $array from right to left and using $zero as first argument.
|
Examples | The following query is equivalent to the expression array:reverse(array { 1 to 5 }) :
array { array:fold-right( array { 1 to 5 }, (), function($a, $b) { $b, $a } ) } |
array:for-each-pair
Signatures | array:for-each-pair($array1 as array(*), $array2 as array(*), $function as function(item()*) as item()*) as array(*)
|
Summary | Returns a new array obtained by evaluating the supplied $function for each pair of members at the same position in $array1 and $array2 .
|
Examples | The following query returns the array [5, 7, 9] :
array:for-each-pair( array { 1 to 3 }, array { 4 to 6 }, function($a + $b) { $a + $b } ) |
array:sort
Signatures | array:sort($array as array(*)) as array(*) array:sort($array as array(*), $collation as xs:string?) as array(*) array:sort($array as array(*), $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*) as array(*) |
Summary | Returns a new array with sorted $array members, using an optional $collation . If a $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 lt expression.
|
Examples |
|
Errors
Code | Description |
---|---|
FOAY0001
|
The specified index extends beyonds the bounds of an array. |
FOAY0002
|
The specified length is less than zero. |
Changelog
- Version 8.6
- Updated: array:put collation argument was inserted between first and second argument.
- Version 8.5
- Added: array:put
- Version 8.4
- Removed: array:serialize (use fn:serialize instead)
Introduced with Version 8.0.