Difference between revisions of "Array Module"
Jump to navigation
Jump to search
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>") |
|||
(48 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
− | This [[Module Library|XQuery Module]] contains functions for manipulating arrays, which has been introduced with [[XQuery 3.1#Arrays|XQuery 3.1]]. | + | This [[Module Library|XQuery Module]] contains functions for manipulating arrays, which has been introduced with [[XQuery 3.1#Arrays|XQuery 3.1]] and extended with [[XQuery 4.0#Arrays|XQuery 4.0]]. |
=Conventions= | =Conventions= | ||
− | All functions 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/> | + | 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: | + | ==array:append== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:append( |
− | |- | + | $array as array(*), |
+ | $member as item()* | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | Returns a copy of {{Code|$array}} with {{Code|$member}} attached. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>array: | + | * <code>array:append([], 'member1')</code> returns the array {{Code|["member1"]}}. |
− | |||
|} | |} | ||
− | ==array: | + | ==array:build== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:build( |
− | |- | + | $input as item()*, |
+ | $action as function(item()) as item()* := fn:identity#1 | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | Returns an {{Code|$array}} obtained by evaluating the supplied function {{Code|$action}} once for each item in the {{Code|$input}} sequence. |
− | + | |- valign="top" | |
− | |||
− | |||
− | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | + | ||
+ | <ul> | ||
+ | <li> | ||
+ | <code>array:build(1 to 5)</code> | ||
+ | returns | ||
+ | <code>[1,2,3,4,5]</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:build(1 to 5, function { 2 * . })</code> | ||
+ | returns | ||
+ | <code>[2,4,6,8,10]</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:build(1 to 5, function { 1 to . })</code> | ||
+ | returns | ||
+ | <code>[1,(1,2),(1,2,3),(1,2,3,4),(1,2,3,4,5)]</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:build(1 to 5, function { array { 1 to . } })</code> | ||
+ | returns | ||
+ | <code>[[1],[1,2],[1,2,3],[1,2,3,4],[1,2,3,4,5]]</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:build(("red", "green", "blue"), characters#1)</code> | ||
+ | returns | ||
+ | <code>[("r","e","d"),("g","r","e","e","n"),("b","l","u","e")]</code> | ||
+ | </li> | ||
+ | </ul> | ||
|} | |} | ||
− | ==array: | + | ==array:empty== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:empty( |
− | |- | + | $array as array(*) |
+ | ) as xs:boolean | ||
+ | </pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | Returns {{Code|true}} if the supplied {{Code|$array}} contains no members. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''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> | ||
+ | </ul> | ||
|} | |} | ||
− | ==array: | + | ==array:exists== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre> |
− | |- | + | array:exists( |
+ | $array as array(*) | ||
+ | ) as xs:boolean | ||
+ | </pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | | + | | Returns {{Code|true}} if the supplied {{Code|$array}} contains one or more members. |
− | + | |- valign="top" | |
− | |||
− | |||
− | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | + | ||
+ | <ul> | ||
+ | <li> | ||
+ | <code>array:exists(["a", "b", "c"])</code> | ||
+ | returns | ||
+ | <code>true()</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:exists([])</code> | ||
+ | returns | ||
+ | <code>false()</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:exists([[]])</code> | ||
+ | returns | ||
+ | <code>true()</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:exists([()])</code> | ||
+ | returns | ||
+ | <code>true()</code> | ||
+ | </li> | ||
+ | </ul> | ||
|} | |} | ||
− | ==array: | + | ==array:filter== |
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:filter( | ||
+ | $array as array(*), | ||
+ | $predicate as function(item()*) as xs:boolean | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Returns a new array with those members of {{Code|$array}} for which {{Code|$predicate}} returns {{Code|true}}. | ||
+ | |- valign="top" | ||
+ | | '''Examples''' | ||
+ | |The following query returns the array {{Code|[0, 1, 3]}}: | ||
+ | <pre lang='xquery'> | ||
+ | array:filter( | ||
+ | array { 0, 1, -2, 3, -4 }, | ||
+ | function($i) { $i > 0 } | ||
+ | ) | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==array:flatten== | ||
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:flatten( |
− | |- | + | $items as item()* |
+ | ) as item()*</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | | + | | Recursively flattens all arrays that occur in the supplied {{Code|$items}}. |
− | + | |- valign="top" | |
− | |||
− | |||
− | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>array: | + | * <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:fold-left== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:fold-left( | ||
+ | $array as array(*), | ||
+ | $zero as item()*, | ||
+ | $action as function(item()*, item()*) as item()* | ||
+ | ) as item()*</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Evaluates the supplied {{Code|$action}} cumulatively on successive members of the supplied {{Code|$array}} from left to right, and uses {{Code|$zero}} as first argument. | ||
+ | |- valign="top" | ||
+ | | '''Examples''' | ||
+ | |The following query returns {{Code|55}} (the sum of the integers 1 to 10): | ||
+ | <pre lang='xquery'> | ||
+ | array:fold-left( | ||
+ | array { 1 to 10 }, | ||
+ | 0, | ||
+ | function($a, $b) { $a + $b } | ||
+ | ) | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==array:fold-right== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:fold-right( | ||
+ | $array as array(*), | ||
+ | $zero as item()*, | ||
+ | $action as function(item()*, item()*) as item()* | ||
+ | ) as item()*</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Evaluates the supplied {{Code|$action}} cumulatively on successive members of the supplied {{Code|$array}} from right to left, and uses {{Code|$zero}} as first argument. | ||
+ | |- valign="top" | ||
+ | | '''Examples''' | ||
+ | |The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>: | ||
+ | <pre lang='xquery'> | ||
+ | array { | ||
+ | array:fold-right( | ||
+ | array { 1 to 5 }, | ||
+ | (), | ||
+ | function($a, $b) { $b, $a } | ||
+ | ) | ||
+ | } | ||
+ | </pre> | ||
|} | |} | ||
− | ==array: | + | ==array:foot== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre> |
− | |- | + | array:foot( |
+ | $array as array(*) | ||
+ | ) as item()* | ||
+ | </pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | Returns the last member of an array, that is {{Code|$array(array:size($array))}}. |
− | + | |- valign="top" | |
− | |||
− | |||
− | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | + | ||
+ | <ul> | ||
+ | <li> | ||
+ | <code>array:foot([5, 6, 7, 8])</code> | ||
+ | returns | ||
+ | <code>8</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:foot([["a", "b"], ["c", "d"]])</code> | ||
+ | returns | ||
+ | <code>["c","d"]</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:foot([("a", "b"), ("c", "d")])</code> | ||
+ | returns 2 results | ||
+ | <code>"c"</code> and <code>"d"</code> | ||
+ | </li> | ||
+ | </ul> | ||
+ | |} | ||
+ | |||
+ | ==array:for-each== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:for-each( | ||
+ | $array as array(*), | ||
+ | $action as function(item()*) as item()* | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Returns a new array, in which each member is computed by applying {{Code|$action}} to the corresponding member of {{Code|$array}}. | ||
+ | |- valign="top" | ||
+ | | '''Examples''' | ||
+ | |The following query returns the array {{Code|[2, 3, 4, 5, 6]}}: | ||
+ | |||
+ | <pre lang='xquery'> | ||
+ | array:for-each( | ||
+ | array { 1 to 5 }, | ||
+ | function($i) { $i + 1} | ||
+ | ) | ||
+ | </pre> | ||
+ | |} | ||
+ | |||
+ | ==array:for-each-pair== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:for-each-pair( | ||
+ | $array1 as array(*), | ||
+ | $array2 as array(*), | ||
+ | $action as function(item()*) as item()* | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Returns a new array obtained by evaluating the supplied {{Code|$action}} for each pair of members at the same position in {{Code|$array1}} and {{Code|$array2}}. | ||
+ | |- valign="top" | ||
+ | | '''Examples''' | ||
+ | |The following query returns the array {{Code|[5, 7, 9]}}: | ||
+ | <pre lang='xquery'> | ||
+ | array:for-each-pair( | ||
+ | array { 1 to 3 }, | ||
+ | array { 4 to 6 }, | ||
+ | function($a + $b) { $a + $b } | ||
+ | ) | ||
+ | </pre> | ||
|} | |} | ||
− | ==array: | + | ==array:get== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:get( |
− | |- | + | $array as array(*), |
+ | $position as xs:integer | ||
+ | ) as item()*</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | Returns the {{Code|$array}} member at the specified {{Code|$position}}. |
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
− | |{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array) | + | |{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>array: | + | * <code>array:get(array { reverse(1 to 5) }, 5)</code> returns the value {{Code|1}}. |
|} | |} | ||
Line 124: | Line 341: | ||
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:head( |
− | |- | + | $array as array(*) |
+ | ) as item()*</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
| Returns the first member of {{Code|$array}}. This function is equivalent to the expression {{Code|$array(1)}}. | | Returns the first member of {{Code|$array}}. This function is equivalent to the expression {{Code|$array(1)}}. | ||
− | |- | + | |- valign="top" |
| '''Errors''' | | '''Errors''' | ||
|{{Error|FOAY0001|#Errors}} The array is empty. | |{{Error|FOAY0001|#Errors}} The array is empty. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
Line 139: | Line 358: | ||
|} | |} | ||
− | ==array: | + | ==array:index-where== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre> |
− | |- | + | array:index-where( |
+ | $array as array(*), | ||
+ | $predicate as function(item()*, xs:integer) as xs:boolean | ||
+ | ) as xs:integer* | ||
+ | </pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | Returns the position in an input {{Code|$array}} of members that match a supplied {{Code|$predicate}}. |
− | + | |- valign="top" | |
− | |||
− | |||
− | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | + | ||
+ | <ul> | ||
+ | <li> | ||
+ | <code>array:index-where([0, (), 4, 9], boolean#1)</code> | ||
+ | returns | ||
+ | <code>()</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:index-where([0, (), 4, 9], boolean#1)</code> | ||
+ | returns | ||
+ | <code>(3, 4)</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <code>array:index-where( | ||
+ | array { 1 to 10 }, | ||
+ | function {. mod 2 = 0 } | ||
+ | )</code> | ||
+ | returns | ||
+ | <code>(2, 4, 6, 8, 10)</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <pre> | ||
+ | array:index-where( | ||
+ | [ "January", "February", "March", "April", | ||
+ | "May", "June", "July", "August", "September", | ||
+ | "October", "November", "December" ], | ||
+ | contains(?, "r") | ||
+ | )</pre> returns <code>(1, 2, 3, 4, 9, 10, 11, 12)</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <pre> | ||
+ | array:index-where( | ||
+ | [(1, 2, 3), (4, 5, 6), (7, 8)], | ||
+ | function($m) { count($m) = 3 } | ||
+ | )</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> | ||
+ | </ul> | ||
|} | |} | ||
− | ==array: | + | ==array:insert-before== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:insert-before( |
− | |- | + | $array as array(*), |
+ | $position as xs:integer, | ||
+ | $member as item()* | ||
+ | ) as array(*) | ||
+ | </pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | Returns an array containing all the members of the supplied {{Code|$array}}, with one additional {{Code|$member}} at a specified {{Code|$position}}. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | + | <ul> | |
+ | <li> | ||
+ | <pre> | ||
+ | array:insert-before( | ||
+ | ["a", "b", "c", "d"], | ||
+ | 3, | ||
+ | ("x", "y") | ||
+ | ) | ||
+ | </pre> returns <code>["a", "b", ("x", "y"), "c", "d"]</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <pre> | ||
+ | array:insert-before( | ||
+ | ["a", "b", "c", "d"], | ||
+ | 5, | ||
+ | ("x", "y") | ||
+ | ) | ||
+ | </pre> returns <code>["a", "b", "c", "d", ("x", "y")]</code> | ||
+ | </li> | ||
+ | <li> | ||
+ | <pre> | ||
+ | array:insert-before( | ||
+ | ["a", "b", "c", "d"], | ||
+ | 3, | ||
+ | ["x", "y"] | ||
+ | ) | ||
+ | </pre> returns <code>["a", "b", ["x", "y"], "c", "d"]</code> | ||
+ | </li> | ||
+ | </ul> | ||
|} | |} | ||
+ | |||
==array:join== | ==array:join== | ||
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:join( |
− | |- | + | $arrays as array(*)* |
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
| Concatenates the contents of several {{Code|$arrays}} into a single array. | | Concatenates the contents of several {{Code|$arrays}} into a single array. | ||
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
* <code>array:join(())</code> returns the array {{Code|[]}}. | * <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((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='120' | '''Signature''' | ||
+ | |<pre>array:members( | ||
+ | $array as array(*) | ||
+ | ) as record(value as item()*)* | ||
+ | </pre> | ||
+ | |- valign="top" | ||
+ | | '''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" | ||
+ | | '''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:of-members== | ||
+ | |||
+ | {| width='100%' | ||
+ | | width='120' | '''Signature''' | ||
+ | |<pre>array:of-members( | ||
+ | $input as record(value as item()*)* | ||
+ | ) as array(*) | ||
+ | </pre> | ||
+ | |- valign="top" | ||
+ | | '''Summary''' | ||
+ | | Constructs an array from the contents of an {{Code|$input}} sequence of value records. | ||
+ | |- valign="top" | ||
+ | | '''Note''' | ||
+ | | This function is the inverse of [[#array:members|array:members]]. | ||
+ | |- valign="top" | ||
+ | | '''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> | ||
|} | |} | ||
− | ==array: | + | ==array:put== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:put( |
− | |- | + | $array as array(*), |
+ | $position as xs:integer, | ||
+ | $member as item()* | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''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>. |
− | |- | + | |- valign="top" |
+ | | '''Errors''' | ||
+ | |{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive. | ||
+ | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>array: | + | * <code>array:put(["a", "b", "c"], 2, "d")</code> returns the array {{Code|["a", "d", "c"]}}. |
− | |||
|} | |} | ||
− | ==array: | + | ==array:remove== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:remove( |
− | |- | + | $array as array(*), |
+ | $positions as xs:integer* | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns a | + | | Returns a copy of {{Code|$array}} without the member at the specified {{Code|$positions}}. |
− | |- | + | |- valign="top" |
+ | | '''Errors''' | ||
+ | |{{Error|FOAY0001|#Errors}} A position is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive. | ||
+ | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
− | | | + | | |
− | < | + | * <code>array:append(["a"], 1)</code> returns the array {{Code|[]}}. |
− | array: | ||
− | |||
− | |||
− | ) | ||
− | </ | ||
|} | |} | ||
− | ==array: | + | ==array:size== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:size( |
− | |- | + | $array as array(*) |
+ | ) as xs:integer</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns | + | | 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''' | | '''Examples''' | ||
− | | | + | | |
− | < | + | * <code>array:size(array { 1 to 10 })</code> returns {{Code|10}}. |
− | array: | + | * <code>array:size([1 to 10])</code> returns {{Code|1}}, because the array contains a single sequence with 10 integers. |
− | |||
− | |||
− | |||
− | </ | ||
|} | |} | ||
− | ==array: | + | ==array:subarray== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:subarray( |
− | |- | + | $array as array(*), |
+ | $position as xs:integer, | ||
+ | $length as xs:integer := () | ||
+ | ) as array(*)</pre> | ||
+ | |- 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" |
+ | | '''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. | ||
+ | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
− | | | + | | |
− | < | + | * <code>array:subarray(["a", "b", "c"], 2)</code> returns the array {{Code|["b", "c"]}}. |
− | array: | ||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
− | ==array: | + | ==array:tail== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:tail( |
− | |- | + | $array as array(*) |
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''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)}}. |
− | |- | + | |- valign="top" |
+ | | '''Errors''' | ||
+ | |{{Error|FOAY0001|#Errors}} The array is empty. | ||
+ | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
− | | | + | | |
− | + | * <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}. | |
− | array { | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | } | ||
− | |||
|} | |} | ||
− | ==array: | + | ==array:reverse== |
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:reverse( |
− | |- | + | $array as array(*) |
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns a new array | + | | Returns a new array with all members of {{Code|$array}} in reverse order. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
− | | | + | | |
− | < | + | * <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}. |
− | array: | ||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
Line 303: | Line 659: | ||
{| width='100%' | {| width='100%' | ||
− | | width='120' | ''' | + | | width='120' | '''Signature''' |
− | | | + | |<pre>array:sort( |
− | |- | + | $array as array(*), |
+ | $collation as xs:string? := (), | ||
+ | $key as function(item()*) as xs:anyAtomicType* := () | ||
+ | ) as array(*)</pre> | ||
+ | |- valign="top" | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns a new array with sorted {{Code|$array}} members. If a | + | | 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. |
− | |- | + | |- valign="top" |
| '''Examples''' | | '''Examples''' | ||
| | | | ||
* <code>array:sort(array { reverse(1 to 3) })</code> returns <code>[1, 2, 3]</code> | * <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([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,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) | + | * <code>array:sort((1,'a'))</code> returns an error (strings and integers cannot be compared) |
|} | |} | ||
Line 322: | Line 682: | ||
! width="110"|Code | ! width="110"|Code | ||
|Description | |Description | ||
− | |- | + | |- valign="top" |
|{{Code|FOAY0001}} | |{{Code|FOAY0001}} | ||
|The specified index extends beyonds the bounds of an array. | |The specified index extends beyonds the bounds of an array. | ||
− | |- | + | |- valign="top" |
|{{Code|FOAY0002}} | |{{Code|FOAY0002}} | ||
|The specified length is less than zero. | |The specified length is less than zero. | ||
Line 331: | Line 691: | ||
+ | =Changelog= | ||
− | + | ;Version 11.0 | |
+ | |||
+ | * Added: {{Function||array:build}} | ||
+ | * Added: {{Function||array:foot}} | ||
+ | * Added: {{Function||array:members}} | ||
+ | * Added: {{Function||array:of-members}} | ||
+ | |||
+ | ;Version 8.6 | ||
+ | * Updated: {{Function||array:put}} collation argument was inserted between first and second argument. | ||
;Version 8.5 | ;Version 8.5 | ||
− | * Added: | + | * Added: {{Function||array:put}} |
;Version 8.4 | ;Version 8.4 |
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.