Difference between revisions of "Array Module"
Jump to navigation
Jump to search
m (Reorder) |
(Added array:empty) |
||
Line 64: | Line 64: | ||
returns | returns | ||
<code>[("r","e","d"),("g","r","e","e","n"),("b","l","u","e")]</code> | <code>[("r","e","d"),("g","r","e","e","n"),("b","l","u","e")]</code> | ||
+ | </li> | ||
+ | </ul> | ||
+ | |} | ||
+ | |||
+ | ==array:empty== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:empty( | ||
+ | $array as array(*) | ||
+ | ) as xs:boolean | ||
+ | </pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Returns {{Code|true}} if the supplied {{Code|$array}} contains no members. | ||
+ | |- valign="top" | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | |||
+ | <ul> | ||
+ | <li> | ||
+ | <code>array:empty(["a", "b", "c"])</code> | ||
+ | returns | ||
+ | <code>false()</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:empty([])</code> | ||
+ | returns | ||
+ | <code>true()</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:empty([[]])</code> | ||
+ | returns | ||
+ | <code>false()</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:empty([()])</code> | ||
+ | returns | ||
+ | <code>false()</code> | ||
</li> | </li> | ||
</ul> | </ul> |
Revision as of 15:00, 16 November 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:size
- 2.5 array:get
- 2.6 array:subarray
- 2.7 array:put
- 2.8 array:remove
- 2.9 array:insert-before
- 2.10 array:head
- 2.11 array:tail
- 2.12 array:reverse
- 2.13 array:join
- 2.14 array:flatten
- 2.15 array:for-each
- 2.16 array:filter
- 2.17 array:fold-left
- 2.18 array:fold-right
- 2.19 array:for-each-pair
- 2.20 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:append
Signature | array:append( $array as array(*), $member as item()* ) as array(*) |
Summary | Returns a copy of $array with $member attached.
|
Examples |
|
array:build
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
Signature | array:empty( $array as array(*) ) as xs:boolean |
Summary | Returns true if the supplied $array contains no members.
|
Examples |
|
array:size
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:get
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:subarray
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:put
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
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:insert-before
Signature | 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
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:tail
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
Signature | array:reverse( $array as array(*) ) as array(*) |
Summary | Returns a new array with all members of $array in reverse order.
|
Examples |
|
array:join
Signature | array:join( $arrays as array(*)* ) as array(*) |
Summary | Concatenates the contents of several $arrays into a single array.
|
Examples |
|
array:flatten
Signature | array:flatten( $items as item()* ) as item()* |
Summary | Recursively flattens all arrays that occur in the supplied $items .
|
Examples |
|
array:for-each
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] :
<syntaxhighlight lang="xquery"> array:for-each( array { 1 to 5 }, function($i) { $i + 1} ) </syntaxhighlight> |
array:filter
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] :
<syntaxhighlight lang="xquery"> array:filter( array { 0, 1, -2, 3, -4 }, function($i) { $i > 0 } ) </syntaxhighlight> |
array:fold-left
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):
<syntaxhighlight lang="xquery"> array:fold-left( array { 1 to 10 }, 0, function($a, $b) { $a + $b } ) </syntaxhighlight> |
array:fold-right
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 }) :
<syntaxhighlight lang="xquery"> array { array:fold-right( array { 1 to 5 }, (), function($a, $b) { $b, $a } ) } </syntaxhighlight> |
array:for-each-pair
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] :
<syntaxhighlight lang="xquery"> array:for-each-pair( array { 1 to 3 }, array { 4 to 6 }, function($a + $b) { $a + $b } ) </syntaxhighlight> |
array:sort
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
Code | Description |
---|---|
FOAY0001
|
The specified index extends beyonds the bounds of an array. |
FOAY0002
|
The specified length is less than zero. |
Changelog
- Version 11.0
- Added:
array:build
- 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.