Difference between revisions of "Array Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>")
 
(67 intermediate revisions by 5 users not shown)
Line 1: Line 1:
This [[Module Library|XQuery Module]] contains functions for manipulating arrays, which will officially be introduced with [[XQuery 3.1#Arrays|XQuery 3.1]].<br/>
+
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]].
'''Please note''' that the functions are subject to change until the specification has reached its final stage.
 
  
 
=Conventions=
 
=Conventions=
  
All functions in this module are assigned to the {{Code|http://www.w3.org/2005/xpath-functions/array}} 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:size==
+
==array:append==
 +
 
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:append(
 +
  $array  as array(*),
 +
  $member  as item()*
 +
) as array(*)</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Returns a copy of {{Code|$array}} with {{Code|$member}} attached.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code>array:append([], 'member1')</code> returns the array {{Code|["member1"]}}.
 +
|}
 +
 
 +
==array:build==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:size|$input as array(*)|xs:integer}}
+
|<pre>array:build(
|-
+
  $input as item()*,
 +
  $action as function(item()) as item()* := fn:identity#1
 +
) as array(*)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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}}.
+
| 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'''
 
|
 
|
* <code>array:size([1 to 10])</code> returns {{Code|10}}.
+
 
* <code>array:size(array { 1 to 10 })</code> returns {{Code|10}}.
+
<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:get==
+
==array:empty==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:get|$array as array(*), $position as xs:integer|item()*}}
+
|<pre>array:empty(
|-
+
  $array as array(*)
 +
) as xs:boolean
 +
</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| Returns the {{Code|$array}} member at the specified {{Code|$position}}.
+
| Returns {{Code|true}} if the supplied {{Code|$array}} contains no members.
|-
+
|- valign="top"
| '''Errors'''
 
|{{Error|FOAY0001|#Errors}}: {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>array:get(array { reverse(1 to 5) }, 5)</code> returns the value {{Code|1}}.
+
 
 +
<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:append==
+
==array:exists==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:append|$array as array(*), $member as item()*|array(*)}}
+
|<pre>
|-
+
array:exists(
 +
  $array as array(*)
 +
) as xs:boolean
 +
</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| Returns a copy of {{Code|$array}} with a new {{Code|$member}} attached.
+
| Returns {{Code|true}} if the supplied {{Code|$array}} contains one or more members.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>array:append([], 'member1')</code> returns the array {{Code|["member1"]}}.
+
 
 +
<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: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:subarray==
+
==array:flatten==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{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(*)}}
+
|<pre>array:flatten(
|-
+
  $items  as item()*
 +
) as item()*</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}}.
+
| Recursively flattens all arrays that occur in the supplied {{Code|$items}}.
|-
+
|- 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.
 
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>array:append(['member1'], 'member2')</code> returns the array {{Code|["member1", "member2"]}}.
+
* <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:remove==
+
==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:foot==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:remove|$array as array(*), $position as xs:integer|array(*)}}
+
|<pre>
|-
+
array:foot(
 +
  $array as array(*)
 +
) as item()*
 +
</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| Returns a copy of {{Code|$array}} without the member at the specified {{Code|$position}}.
+
| Returns the last member of an array, that is {{Code|$array(array:size($array))}}.
|-
+
|- valign="top"
| '''Errors'''
 
|{{Error|FOAY0001|#Errors}}: {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>array:append(["a"], 1)</code> returns the array {{Code|[]}}.
+
 
 +
<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:insert-before==
+
==array:get==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:insert-before|$array as array(*), $position as xs:integer, $member as item()*|array(*)}}
+
|<pre>array:get(
|-
+
  $array     as array(*),
 +
  $position as xs:integer
 +
) as item()*</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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)}}.
+
| 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) + 1}} inclusive.
+
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.
+
* <code>array:get(array { reverse(1 to 5) }, 5)</code> returns the value {{Code|1}}.
 
|}
 
|}
  
Line 108: Line 341:
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:head|$array as array(*)|item()*}}
+
|<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 123: Line 358:
 
|}
 
|}
  
==array:tail==
+
==array:index-where==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:tail|$array as array(*)|array(*)}}
+
|<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 a new array with all members except the first from {{Code|$array}}. This function is equivalent to the expression {{Code|array:remove($array, 1)}}.
+
| Returns the position in an input {{Code|$array}} of members that match a supplied {{Code|$predicate}}.
|-
+
|- valign="top"
| '''Errors'''
 
|{{Error|FOAY0001|#Errors}}: The array is empty.
 
|-
 
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.
+
 
 +
<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:reverse==
+
==array:insert-before==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:reverse|$array as array(*)|array(*)}}
+
|<pre>array:insert-before(
|-
+
  $array as array(*),
 +
  $position as xs:integer,
 +
  $member as item()*
 +
) as array(*)
 +
</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| Returns a new array with all members of {{Code|$array}} in reverse order.
+
| 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'''
 
|
 
|
* <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}.
+
<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' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:join|$arrays as array(*)*|array(*)}}
+
|<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:for-each==
+
==array:members==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:for-each|$array as array(*), $function as function(item()*) as item()*|array(*)}}
+
|<pre>array:members(
|-
+
  $array as array(*)
 +
) as record(value as item()*)*
 +
</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| Returns a new array, in which each member is computed by applying {{Code|$function}} to the corresponding member of {{Code|$array}}.
+
| 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'''
 
| '''Examples'''
|The following query returns the array {{Code|[2, 3, 4, 5, 6]}}:
+
|
<pre class="brush:xquery">
+
<ul>
array:for-each(
+
  <li><code>array:members([])</code> returns {{Code|()}}.</li>
   array { 1 to 5 },
+
  <li><code>array:members([1 to 5])?value</code> returns {{Code|(1, 2, 3, 4, 5)}}.</li>
   function($i) { $i + 1}
+
  <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>
 
</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:put==
 +
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:put(
 +
  $array    as array(*),
 +
  $position  as xs:integer,
 +
  $member    as item()*
 +
) as array(*)</pre>
 +
|- valign="top"
 +
| '''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'''
 +
|
 +
* <code>array:put(["a", "b", "c"], 2, "d")</code> returns the array {{Code|["a", "d", "c"]}}.
 +
|}
 +
 +
==array:remove==
 +
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:remove(
 +
  $array      as array(*),
 +
  $positions  as xs:integer*
 +
) as array(*)</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| 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'''
 +
|
 +
* <code>array:append(["a"], 1)</code> returns the array {{Code|[]}}.
 
|}
 
|}
  
==array:filter==
+
==array:size==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:filter|$array as array(*), $function as function(item()*) as xs:boolean|array(*)}}
+
|<pre>array:size(
|-
+
  $array as array(*)
 +
) as xs:integer</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| Returns a new array with those members of {{$array}} for which {{Code|$function}} returns {{Code|true}}.
+
| 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'''
|The following query returns the array {{Code|[0, 1, 3]}}:
+
|
<pre class="brush:xquery">
+
* <code>array:size(array { 1 to 10 })</code> returns {{Code|10}}.
array:filter(
+
* <code>array:size([1 to 10])</code> returns {{Code|1}}, because the array contains a single sequence with 10 integers.
  array { 0, 1, -2, 3, -4 },
 
  function($i) { $i > 0 }
 
)
 
</pre>
 
 
|}
 
|}
  
==array:fold-left==
+
==array:subarray==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:fold-left|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}
+
|<pre>array:subarray(
|-
+
  $array     as array(*),
 +
  $position  as xs:integer,
 +
  $length    as xs:integer  := ()
 +
) as array(*)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
+
| 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'''
|The following query returns {{Code|55}} (the sum of the integers 1 to 10):
+
|
<pre class="brush:xquery">
+
* <code>array:subarray(["a", "b", "c"], 2)</code> returns the array {{Code|["b", "c"]}}.
array:fold-left(
 
  array { 1 to 10 },
 
  0,
 
  function($a, $b) { $a + $b }
 
)
 
</pre>
 
 
|}
 
|}
  
==array:fold-right==
+
==array:tail==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:fold-right|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}
+
|<pre>array:tail(
|-
+
  $array as array(*)
 +
) as array(*)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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.
+
| 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'''
|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:
+
|
<pre class="brush:xquery">
+
* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.
array {
 
  array:fold-right(
 
    array { 1 to 5 },
 
    (),
 
    function($a, $b) { $b, $a }
 
  )
 
}
 
</pre>
 
 
|}
 
|}
  
==array:for-each-pair==
+
==array:reverse==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|array:for-each-pair|$array1 as array(*), $array2 as array(*), $function as function(item()*) as item()*|array(*)}}
+
|<pre>array:reverse(
|-
+
  $array as array(*)
 +
) as array(*)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''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}}.
+
| Returns a new array with all members of {{Code|$array}} in reverse order.
|-
+
|- valign="top"
 
| '''Examples'''
 
| '''Examples'''
|The following query returns the array {{Code|[5, 7, 9]}}:
+
|
<pre class="brush:xquery">
+
* <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}.
array:for-each-pair(
 
  array { 1 to 3 },
 
  array { 4 to 6 },
 
  function($a + $b) { $a + $b }
 
)
 
</pre>
 
 
|}
 
|}
  
==array:serialize==
+
==array:sort==
  
 
{| width='100%'
 
{| width='100%'
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
|{{Func|map:serialize|$input as map(*)|xs:string}}<br/>
+
|<pre>array:sort(
|-
+
  $array      as array(*),
 +
  $collation  as xs:string?                            := (),
 +
  $key        as function(item()*) as xs:anyAtomicType* := ()
 +
) as array(*)</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
| This function is specific to BaseX. It returns a string representation of the supplied array. The purpose of this function is to get an insight into the structure of an array item; it cannot necessarily be used for reconstructing the original array.
+
| 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:serialize([ 1, (2, 3), 4 to 6 ])</code> returns <code>[1, (2, 3), (4, 5, 6)]</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([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)
 
|}
 
|}
  
Line 288: 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.
 
|}
 
|}
  
[[Category:XQuery]]
 
  
 
=Changelog=
 
=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
 +
* Added: {{Function||array:put}}
 +
 +
;Version 8.4
 +
* Removed: array:serialize (use fn:serialize instead)
  
 
Introduced with Version 8.0.
 
Introduced with Version 8.0.
 
[[Category:XQuery]]
 

Latest revision as of 17: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.

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:append([], 'member1') returns the array ["member1"].

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:build(1 to 5) returns [1,2,3,4,5]
  • array:build(1 to 5, function { 2 * . }) returns [2,4,6,8,10]
  • array:build(1 to 5, function { 1 to . }) returns [1,(1,2),(1,2,3),(1,2,3,4),(1,2,3,4,5)]
  • array:build(1 to 5, function { array { 1 to . } }) returns [[1],[1,2],[1,2,3],[1,2,3,4],[1,2,3,4,5]]
  • array:build(("red", "green", "blue"), characters#1) returns [("r","e","d"),("g","r","e","e","n"),("b","l","u","e")]

array:empty[edit]

Signature
array:empty(
  $array	as array(*)	
) as xs:boolean
Summary Returns true if the supplied $array contains no members.
Examples
  • array:empty(["a", "b", "c"]) returns false()
  • array:empty([]) returns true()
  • array:empty([[]]) returns false()
  • array:empty([()]) returns false()

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:exists(["a", "b", "c"]) returns true()
  • array:exists([]) returns false()
  • array:exists([[]]) returns true()
  • array:exists([()]) returns true()

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:flatten(["a","b"]) returns the sequence "a", "b".
  • array:flatten([1,[2,3],4]]) returns the sequence 1, 2, 3, 4.

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:foot([5, 6, 7, 8]) returns 8
  • array:foot([["a", "b"], ["c", "d"]]) returns ["c","d"]
  • array:foot([("a", "b"), ("c", "d")]) returns 2 results "c" and "d"

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:get(array { reverse(1 to 5) }, 5) returns the value 1.

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:head(["a", "b"]) returns "a".
  • array:head([["a", "b"], ["c", "d"]]) returns the array ["a", "b"].

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:index-where([0, (), 4, 9], boolean#1) returns ()
  • array:index-where([0, (), 4, 9], boolean#1) returns (3, 4)
  • array:index-where( array { 1 to 10 }, function {. mod 2 = 0 } ) returns (2, 4, 6, 8, 10)
  • array:index-where(
      [ "January", "February", "March", "April",
        "May", "June", "July", "August", "September",
        "October", "November", "December" ],
      contains(?, "r")
    )
    returns (1, 2, 3, 4, 9, 10, 11, 12)
  • array:index-where(
      [(1, 2, 3), (4, 5, 6), (7, 8)],
      function($m) { count($m) = 3 }
    )
    returns (1, 2)
  • array:index-where(
      [ 1, 8, 2, 7, 3 ],
      fn($member, $pos) { $member < 5 and $pos > 2 }
    )
    returns (3, 5)

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:insert-before(
      ["a", "b", "c", "d"],
      3,
      ("x", "y")
    )
    
    returns ["a", "b", ("x", "y"), "c", "d"]
  • array:insert-before(
      ["a", "b", "c", "d"],
      5,
      ("x", "y")
    )
    
    returns ["a", "b", "c", "d", ("x", "y")]
  • array:insert-before(
      ["a", "b", "c", "d"],
      3,
      ["x", "y"]
    )
    
    returns ["a", "b", ["x", "y"], "c", "d"]


array:join[edit]

Signature
array:join(
  $arrays  as array(*)*
) as array(*)
Summary Concatenates the contents of several $arrays into a single array.
Examples
  • array:join(()) returns the array [].
  • array:join((1 to 3) ! array { . }) returns the array [1, 2, 3].
  • array:join((["a", "b"], ["c", "d"])) returns the array ["a", "b", "c", "d"].
  • array:join((["a", "b"], ["c", "d"], [ ])) returns the array ["a", "b", "c", "d"].
  • array:join((["a", "b"], ["c", "d"], "e", "f")) returns the array ["a", "b", "c", "d", ["e", "f"]].

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:members([]) returns ().
  • array:members([1 to 5])?value returns (1, 2, 3, 4, 5).
  • array:members([(1,1), (2,4), (3,9), (4,16), (5,25)]) ! sum(?value) returns (2, 6, 12, 20, 30).
  • let $array := [ "any array" ]
    return deep-equal(
      $array,
      array:of-members(array:members($array))
    )
    returns true()

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:of-members(()) returns [].
  • array:of-members(map { 'value': (1 to 5) }) returns [(1, 2, 3, 4, 5)].
  • array:of-members((1 to 5) ! map { 'value': . }) returns [1, 2, 3, 4, 5].
  • array:of-members((1 to 5) ! map { 'value': (., .*.) }) returns [(1, 1), (2, 4), (3, 9), (4, 16), (5, 25)].

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:put(["a", "b", "c"], 2, "d") returns the array ["a", "d", "c"].

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:append(["a"], 1) returns the array [].

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:size(array { 1 to 10 }) returns 10.
  • array:size([1 to 10]) returns 1, because the array contains a single sequence with 10 integers.

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:subarray(["a", "b", "c"], 2) returns the array ["b", "c"].

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:insert-before(["a"], 1, "b") returns the array ["b", "a"].

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:reverse(array { 1 to 3 }) returns the array [3, 2, 1].

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
  • array:sort(array { reverse(1 to 3) }) returns [1, 2, 3]
  • array:sort([3,-2,1], (), abs#1) returns [1, -2, 3]
  • array:sort([1,2,3], (), function($x) { -$x }) returns [3, 2, 1]
  • array:sort((1,'a')) returns an error (strings and integers cannot be compared)

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
Version 8.6
  • Updated: array:put collation argument was inserted between first and second argument.
Version 8.5
Version 8.4
  • Removed: array:serialize (use fn:serialize instead)

Introduced with Version 8.0.