Difference between revisions of "Array Module"
Jump to navigation
Jump to search
(Added array:insert-before) |
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>") |
||
(8 intermediate revisions by 3 users not shown) | |||
Line 7: | Line 7: | ||
=Functions= | =Functions= | ||
− | ==array:append== | + | ==array:append== |
{| width='100%' | {| width='100%' | ||
Line 161: | Line 161: | ||
| '''Examples''' | | '''Examples''' | ||
|The following query returns the array {{Code|[0, 1, 3]}}: | |The following query returns the array {{Code|[0, 1, 3]}}: | ||
− | < | + | <pre lang='xquery'> |
array:filter( | array:filter( | ||
array { 0, 1, -2, 3, -4 }, | array { 0, 1, -2, 3, -4 }, | ||
function($i) { $i > 0 } | function($i) { $i > 0 } | ||
) | ) | ||
− | </ | + | </pre> |
|} | |} | ||
Line 201: | Line 201: | ||
| '''Examples''' | | '''Examples''' | ||
|The following query returns {{Code|55}} (the sum of the integers 1 to 10): | |The following query returns {{Code|55}} (the sum of the integers 1 to 10): | ||
− | < | + | <pre lang='xquery'> |
array:fold-left( | array:fold-left( | ||
array { 1 to 10 }, | array { 1 to 10 }, | ||
Line 207: | Line 207: | ||
function($a, $b) { $a + $b } | function($a, $b) { $a + $b } | ||
) | ) | ||
− | </ | + | </pre> |
|} | |} | ||
Line 225: | Line 225: | ||
| '''Examples''' | | '''Examples''' | ||
|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>: | |The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>: | ||
− | < | + | <pre lang='xquery'> |
array { | array { | ||
array:fold-right( | array:fold-right( | ||
Line 233: | Line 233: | ||
) | ) | ||
} | } | ||
− | </ | + | </pre> |
|} | |} | ||
Line 286: | Line 286: | ||
|The following query returns the array {{Code|[2, 3, 4, 5, 6]}}: | |The following query returns the array {{Code|[2, 3, 4, 5, 6]}}: | ||
− | < | + | <pre lang='xquery'> |
array:for-each( | array:for-each( | ||
array { 1 to 5 }, | array { 1 to 5 }, | ||
function($i) { $i + 1} | function($i) { $i + 1} | ||
) | ) | ||
− | </ | + | </pre> |
|} | |} | ||
Line 309: | Line 309: | ||
| '''Examples''' | | '''Examples''' | ||
|The following query returns the array {{Code|[5, 7, 9]}}: | |The following query returns the array {{Code|[5, 7, 9]}}: | ||
− | < | + | <pre lang='xquery'> |
array:for-each-pair( | array:for-each-pair( | ||
array { 1 to 3 }, | array { 1 to 3 }, | ||
Line 315: | Line 315: | ||
function($a + $b) { $a + $b } | function($a + $b) { $a + $b } | ||
) | ) | ||
− | </ | + | </pre> |
|} | |} | ||
Line 409: | Line 409: | ||
function($m) { count($m) = 3 } | function($m) { count($m) = 3 } | ||
)</pre> returns <code>(1, 2)</code> | )</pre> returns <code>(1, 2)</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <pre> | ||
+ | array:index-where( | ||
+ | [ 1, 8, 2, 7, 3 ], | ||
+ | fn($member, $pos) { $member < 5 and $pos > 2 } | ||
+ | )</pre> returns <code>(3, 5)</code> | ||
</li> | </li> | ||
</ul> | </ul> | ||
Line 460: | Line 467: | ||
|} | |} | ||
− | ==array: | + | |
+ | ==array:join== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:join( | ||
+ | $arrays as array(*)* | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Concatenates the contents of several {{Code|$arrays}} into a single array. | ||
+ | |- valign="top" | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * <code>array:join(())</code> returns the array {{Code|[]}}. | ||
+ | * <code>array:join((1 to 3) ! array { . })</code> returns the array {{Code|[1, 2, 3]}}. | ||
+ | * <code>array:join((["a", "b"], ["c", "d"]))</code> returns the array {{Code|["a", "b", "c", "d"]}}. | ||
+ | * <code>array:join((["a", "b"], ["c", "d"], [ ]))</code> returns the array {{Code|["a", "b", "c", "d"]}}. | ||
+ | * <code>array:join((["a", "b"], ["c", "d"], [["e", "f"]]))</code> returns the array {{Code|["a", "b", "c", "d", ["e", "f"]]}}. | ||
+ | |} | ||
+ | |||
+ | ==array:members== | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
− | |<pre>array: | + | |<pre>array:members( |
− | $array | + | $array as array(*) |
− | ) as | + | ) as record(value as item()*)* |
+ | </pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | | + | | Delivers the contents of an {{Code|$array}} as a sequence of value records. |
+ | |- valign="top" | ||
+ | | '''Note''' | ||
+ | | This function is the inverse of [[#array:of-members|array:of-members]]. | ||
|- valign="top" | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | + | <ul> | |
− | + | <li><code>array:members([])</code> returns {{Code|()}}.</li> | |
+ | <li><code>array:members([1 to 5])?value</code> returns {{Code|(1, 2, 3, 4, 5)}}.</li> | ||
+ | <li><code>array:members([(1,1), (2,4), (3,9), (4,16), (5,25)]) ! sum(?value)</code> returns {{Code|(2, 6, 12, 20, 30)}}.</li> | ||
+ | <li><pre>let $array := [ "any array" ] | ||
+ | return deep-equal( | ||
+ | $array, | ||
+ | array:of-members(array:members($array)) | ||
+ | )</pre> returns {{Code|true()}}</li> | ||
+ | </ul> | ||
|} | |} | ||
− | ==array: | + | ==array:of-members== |
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
− | |<pre>array: | + | |<pre>array:of-members( |
− | $ | + | $input as record(value as item()*)* |
− | + | ) as array(*) | |
− | + | </pre> | |
− | ) as array(*)</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Constructs | + | | Constructs an array from the contents of an {{Code|$input}} sequence of value records. |
|- valign="top" | |- valign="top" | ||
− | | ''' | + | | '''Note''' |
− | | | + | | This function is the inverse of [[#array:members|array:members]]. |
|- valign="top" | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | + | <ul> | |
+ | <li><code>array:of-members(())</code> returns {{Code|[]}}.</li> | ||
+ | <li><code>array:of-members(map { 'value': (1 to 5) })</code> returns {{Code|[(1, 2, 3, 4, 5)]}}.</li> | ||
+ | <li><code>array:of-members((1 to 5) ! map { 'value': . })</code> returns {{Code|[1, 2, 3, 4, 5]}}.</li> | ||
+ | <li><code>array:of-members((1 to 5) ! map { 'value': (., .*.) })</code> returns {{Code|[(1, 1), (2, 4), (3, 9), (4, 16), (5, 25)]}}.</li> | ||
+ | </ul> | ||
|} | |} | ||
Line 539: | Line 583: | ||
|} | |} | ||
− | ==array: | + | ==array:size== |
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:size( | ||
+ | $array as array(*) | ||
+ | ) as xs:integer</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | 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}}. | ||
+ | |- valign="top" | ||
+ | | '''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:subarray== | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signature''' | | width='120' | '''Signature''' | ||
− | |<pre>array: | + | |<pre>array:subarray( |
$array as array(*), | $array as array(*), | ||
$position as xs:integer, | $position as xs:integer, | ||
− | $ | + | $length as xs:integer := () |
) as array(*)</pre> | ) as array(*)</pre> | ||
|- valign="top" | |- valign="top" | ||
| '''Summary''' | | '''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}}. |
|- valign="top" | |- valign="top" | ||
| '''Errors''' | | '''Errors''' | ||
− | |{{Error|FOAY0001|#Errors}} {{Code|$position}} is | + | |{{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. |
|- valign="top" | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>array: | + | * <code>array:subarray(["a", "b", "c"], 2)</code> returns the array {{Code|["b", "c"]}}. |
|} | |} | ||
Line 593: | Line 654: | ||
| | | | ||
* <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}. | * <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
Line 653: | Line 697: | ||
* Added: {{Function||array:build}} | * Added: {{Function||array:build}} | ||
* Added: {{Function||array:foot}} | * Added: {{Function||array:foot}} | ||
+ | * Added: {{Function||array:members}} | ||
+ | * Added: {{Function||array:of-members}} | ||
;Version 8.6 | ;Version 8.6 |
Latest revision as of 18:35, 1 December 2023
This XQuery Module contains functions for manipulating arrays, which has been introduced with XQuery 3.1 and extended with XQuery 4.0.
Contents
- 1 Conventions
- 2 Functions
- 2.1 array:append
- 2.2 array:build
- 2.3 array:empty
- 2.4 array:exists
- 2.5 array:filter
- 2.6 array:flatten
- 2.7 array:fold-left
- 2.8 array:fold-right
- 2.9 array:foot
- 2.10 array:for-each
- 2.11 array:for-each-pair
- 2.12 array:get
- 2.13 array:head
- 2.14 array:index-where
- 2.15 array:insert-before
- 2.16 array:join
- 2.17 array:members
- 2.18 array:of-members
- 2.19 array:put
- 2.20 array:remove
- 2.21 array:size
- 2.22 array:subarray
- 2.23 array:tail
- 2.24 array:reverse
- 2.25 array:sort
- 3 Errors
- 4 Changelog
Conventions[edit]
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[edit]
array:append[edit]
Signature | array:append( $array as array(*), $member as item()* ) as array(*) |
Summary | Returns a copy of $array with $member attached.
|
Examples |
|
array:build[edit]
Signature | array:build( $input as item()*, $action as function(item()) as item()* := fn:identity#1 ) as array(*) |
Summary | Returns an $array obtained by evaluating the supplied function $action once for each item in the $input sequence.
|
Examples |
|
array:empty[edit]
Signature | array:empty( $array as array(*) ) as xs:boolean |
Summary | Returns true if the supplied $array contains no members.
|
Examples |
|
array:exists[edit]
Signature | array:exists( $array as array(*) ) as xs:boolean |
Summary | Returns true if the supplied $array contains one or more members.
|
Examples |
|
array:filter[edit]
Signature | array:filter( $array as array(*), $predicate as function(item()*) as xs:boolean ) as array(*) |
Summary | Returns a new array with those members of $array for which $predicate 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:flatten[edit]
Signature | array:flatten( $items as item()* ) as item()* |
Summary | Recursively flattens all arrays that occur in the supplied $items .
|
Examples |
|
array:fold-left[edit]
Signature | array:fold-left( $array as array(*), $zero as item()*, $action as function(item()*, item()*) as item()* ) as item()* |
Summary | Evaluates the supplied $action cumulatively on successive members of the supplied $array from left to right, and uses $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[edit]
Signature | array:fold-right( $array as array(*), $zero as item()*, $action as function(item()*, item()*) as item()* ) as item()* |
Summary | Evaluates the supplied $action cumulatively on successive members of the supplied $array from right to left, and uses $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:foot[edit]
Signature | array:foot( $array as array(*) ) as item()* |
Summary | Returns the last member of an array, that is $array(array:size($array)) .
|
Examples |
|
array:for-each[edit]
Signature | array:for-each( $array as array(*), $action as function(item()*) as item()* ) as array(*) |
Summary | Returns a new array, in which each member is computed by applying $action 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:for-each-pair[edit]
Signature | array:for-each-pair( $array1 as array(*), $array2 as array(*), $action as function(item()*) as item()* ) as array(*) |
Summary | Returns a new array obtained by evaluating the supplied $action 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:get[edit]
Signature | 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:head[edit]
Signature | 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:index-where[edit]
Signature | array:index-where( $array as array(*), $predicate as function(item()*, xs:integer) as xs:boolean ) as xs:integer* |
Summary | Returns the position in an input $array of members that match a supplied $predicate .
|
Examples |
|
array:insert-before[edit]
Signature | array:insert-before( $array as array(*), $position as xs:integer, $member as item()* ) as array(*) |
Summary | Returns an array containing all the members of the supplied $array , with one additional $member at a specified $position .
|
Examples |
|
array:join[edit]
Signature | array:join( $arrays as array(*)* ) as array(*) |
Summary | Concatenates the contents of several $arrays into a single array.
|
Examples |
|
array:members[edit]
Signature | array:members( $array as array(*) ) as record(value as item()*)* |
Summary | Delivers the contents of an $array as a sequence of value records.
|
Note | This function is the inverse of array:of-members. |
Examples |
|
array:of-members[edit]
Signature | array:of-members( $input as record(value as item()*)* ) as array(*) |
Summary | Constructs an array from the contents of an $input sequence of value records.
|
Note | This function is the inverse of array:members. |
Examples |
|
array:put[edit]
Signature | 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[edit]
Signature | 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:size[edit]
Signature | array:size( $array 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:subarray[edit]
Signature | 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:tail[edit]
Signature | 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[edit]
Signature | array:reverse( $array as array(*) ) as array(*) |
Summary | Returns a new array with all members of $array in reverse order.
|
Examples |
|
array:sort[edit]
Signature | 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[edit]
Code | Description |
---|---|
FOAY0001
|
The specified index extends beyonds the bounds of an array. |
FOAY0002
|
The specified length is less than zero. |
Changelog[edit]
- Version 11.0
- Added:
array:build
- Added:
array:foot
- Added:
array:members
- Added:
array:of-members
- 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.