Difference between revisions of "Array Module"

From BaseX Documentation
Jump to navigation Jump to search
(Created page with "This XQuery Module contains functions for manipulating arrays, which will officially be introduced with XQuery 3.1. =Conventions= All f...")
 
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>")
 
(94 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]].
+
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|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: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='120' | '''Signature'''
 +
|<pre>array:build(
 +
  $input as item()*,
 +
  $action as function(item()) as item()* := fn:identity#1
 +
) as array(*)</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Returns an {{Code|$array}} obtained by evaluating the supplied function {{Code|$action}} once for each item in the {{Code|$input}} sequence.
 +
|- valign="top"
 +
| '''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: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>
 +
</ul>
 +
|}
 +
 +
==array:exists==
 +
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>
 +
array:exists(
 +
  $array as array(*)
 +
) as xs:boolean
 +
</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Returns {{Code|true}} if the supplied {{Code|$array}} contains one or more members.
 +
|- valign="top"
 +
| '''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: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='120' | '''Signature'''
 +
|<pre>array:flatten(
 +
  $items  as item()*
 +
) as item()*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Recursively flattens all arrays that occur in the supplied {{Code|$items}}.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code>array:flatten(["a","b"])</code> returns the sequence {{Code|"a", "b"}}.
 +
* <code>array:flatten([1,[2,3],4]])</code> returns the sequence {{Code|1, 2, 3, 4}}.
 +
|}
 +
 +
==array: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:foot==
 +
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>
 +
array:foot(
 +
  $array as array(*)
 +
) as item()*
 +
</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Returns the last member of an array, that is {{Code|$array(array:size($array))}}.
 +
|- valign="top"
 +
| '''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:get==
 +
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:get(
 +
  $array    as array(*),
 +
  $position  as xs:integer
 +
) as item()*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Returns the {{Code|$array}} member at the specified {{Code|$position}}.
 +
|- 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:get(array { reverse(1 to 5) }, 5)</code> returns the value {{Code|1}}.
 +
|}
 +
 +
==array:head==
 +
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:head(
 +
  $array  as array(*)
 +
) as item()*</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Returns the first member of {{Code|$array}}. This function is equivalent to the expression {{Code|$array(1)}}.
 +
|- valign="top"
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} The array is empty.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code>array:head(["a", "b"])</code> returns {{Code|"a"}}.
 +
* <code>array:head([["a", "b"], ["c", "d"]])</code> returns the array {{Code|["a", "b"]}}.
 +
|}
 +
 +
==array:index-where==
 +
 +
{| width='100%'
 +
| 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'''
 +
| Returns the position in an input {{Code|$array}} of members that match a supplied {{Code|$predicate}}.
 +
|- valign="top"
 +
| '''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:insert-before==
 +
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:insert-before(
 +
  $array as array(*),
 +
  $position as xs:integer,
 +
  $member as item()*
 +
) as array(*)
 +
</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| 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'''
 +
|
 +
<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==
 +
 +
{| 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='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: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:size==
 
==array:size==
 +
 
{| width='100%'
 
{| width='100%'
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|array:size|$input as array(*)|xs:integer}}
+
|<pre>array:size(
−
|-
+
  $array  as array(*)
 +
) as xs:integer</pre>
 +
|- valign="top"
 
| '''Summary'''
 
| '''Summary'''
−
| Returns the number of members in the supplied array. Note that because an array is an item, the {{Code|fn:count}} function when applied to an array always returns {{Code|1}}.
+
| 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([1 to 10])</code> returns {{Code|10}}.
 
 
* <code>array:size(array { 1 to 10 })</code> returns {{Code|10}}.
 
* <code>array:size(array { 1 to 10 })</code> returns {{Code|10}}.
 +
* <code>array:size([1 to 10])</code> returns {{Code|1}}, because the array contains a single sequence with 10 integers.
 
|}
 
|}
  
−
==array:serialize==
+
==array:subarray==
  
 
{| width='100%'
 
{| width='100%'
−
| width='120' | '''Signatures'''
+
| width='120' | '''Signature'''
−
|{{Func|map:serialize|$input as map(*)|xs:string}}<br/>
+
|<pre>array:subarray(
−
|-
+
  $array    as array(*),
 +
  $position  as xs:integer,
 +
  $length    as xs:integer  := ()
 +
) 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.
+
| 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:serialize([ 1, (2, 3), 4 to 6 ])</code> returns <code>[1, (2, 3), (4, 5, 6)]</code>.
+
* <code>array:subarray(["a", "b", "c"], 2)</code> returns the array {{Code|["b", "c"]}}.
 +
|}
 +
 
 +
==array:tail==
 +
 
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:tail(
 +
  $array  as array(*)
 +
) as array(*)</pre>
 +
|- valign="top"
 +
| '''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'''
 +
|
 +
* <code>array:insert-before(["a"], 1, "b")</code> returns the array {{Code|["b", "a"]}}.
 +
|}
 +
 
 +
==array:reverse==
 +
 
 +
{| width='100%'
 +
| width='120' | '''Signature'''
 +
|<pre>array:reverse(
 +
  $array  as array(*)
 +
) as array(*)</pre>
 +
|- valign="top"
 +
| '''Summary'''
 +
| Returns a new array with all members of {{Code|$array}} in reverse order.
 +
|- valign="top"
 +
| '''Examples'''
 +
|
 +
* <code>array:reverse(array { 1 to 3 })</code> returns the array {{Code|[3, 2, 1]}}.
 +
|}
 +
 
 +
==array:sort==
 +
 
 +
{| width='100%'
 +
| 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'''
 +
| 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'''
 +
|
 +
* <code>array:sort(array { reverse(1 to 3) })</code> returns <code>[1, 2, 3]</code>
 +
* <code>array:sort([3,-2,1], (), abs#1)</code> returns <code>[1, -2, 3]</code>
 +
* <code>array:sort([1,2,3], (), function($x) { -$x })</code> returns <code>[3, 2, 1]</code>
 +
* <code>array:sort((1,'a'))</code> returns an error (strings and integers cannot be compared)
 +
|}
 +
 
 +
=Errors=
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="110"|Code
 +
|Description
 +
|- valign="top"
 +
|{{Code|FOAY0001}}
 +
|The specified index extends beyonds the bounds of an array.
 +
|- valign="top"
 +
|{{Code|FOAY0002}}
 +
|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 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.

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.

Retrieved from "http://docs.basex.org/index.php?title=Array_Module&oldid=16827"