Difference between revisions of "Array Module"

From BaseX Documentation
Jump to navigation Jump to search
 
(33 intermediate revisions by 3 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]].
'''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=
Line 19: Line 18:
 
| '''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.
 
|}
 
|}
  
Line 33: Line 32:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
+
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 64: Line 63:
 
|-
 
|-
 
| '''Errors'''
 
| '''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.
+
|{{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:subarray(["a", "b", "c"], 2)</code> returns the array {{Code|["b", "c"]}}.
 +
|}
 +
 
 +
==array:put==
 +
 
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:put|$array as array(*), $position as xs:integer, $member as item()*|array(*)}}
 +
|-
 +
| '''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>.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:put(["a", "b", "c"], 2, "d")</code> returns the array {{Code|["a", "d", "c"]}}.
 
|}
 
|}
  
Line 75: Line 91:
 
{| width='100%'
 
{| width='100%'
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|array:remove|$array as array(*), $index as xs:integer|array(*)}}
+
|{{Func|array:remove|$array as array(*), $positions as xs:integer*|array(*)}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
| Returns a copy of {{Code|$array}} without the member at the specified {{Code|$index}}.  
+
| Returns a copy of {{Code|$array}} without the member at the specified {{Code|$positions}}.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: {{Code|$index}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
+
|{{Error|FOAY0001|#Errors}} A position is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 92: Line 108:
 
{| width='100%'
 
{| width='100%'
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|array:insert-before|$array as array(*), $index as xs:integer, $member as item()*|array(*)}}
+
|{{Func|array:insert-before|$array as array(*), $position as xs:integer, $member as item()*|array(*)}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
| Returns a copy of {{Code|$array}} with one new {{Code|$member}} at the specified {{Code|$index}}. Setting {{Code|$index}} to the value {{Code|array:size($array) + 1}} yields the same result as {{Code|array:append($array, $insert)}}.
+
| 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)}}.
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: {{Code|$index}} 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) + 1}} inclusive.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 115: Line 131:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: The array is empty.
+
|{{Error|FOAY0001|#Errors}} The array is empty.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 133: Line 149:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: The array is empty.
+
|{{Error|FOAY0001|#Errors}} The array is empty.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 167: Line 183:
 
* <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]}}.
 +
|}
 +
 +
==array:flatten==
 +
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:flatten|$items as item()*|item()*}}
 +
|-
 +
| '''Summary'''
 +
| Recursively flattens all arrays that occur in the supplied {{Code|$items}}.
 +
|-
 +
| '''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}}.
 
|}
 
|}
  
Line 180: Line 211:
 
| '''Examples'''
 
| '''Examples'''
 
|The following query returns the array {{Code|[2, 3, 4, 5, 6]}}:
 
|The following query returns the array {{Code|[2, 3, 4, 5, 6]}}:
<pre class="brush:xquery">
+
 
 +
<syntaxhighlight lang="xquery">
 
array:for-each(
 
array:for-each(
 
   array { 1 to 5 },
 
   array { 1 to 5 },
 
   function($i) { $i + 1}
 
   function($i) { $i + 1}
 
)
 
)
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 195: Line 227:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
| Returns a new array with those members of {{$array}} for which {{Code|$function}} returns {{Code|true}}.
+
| Returns a new array with those members of {{Code|$array}} for which {{Code|$function}} returns {{Code|true}}.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
 
|The following query returns the array {{Code|[0, 1, 3]}}:
 
|The following query returns the array {{Code|[0, 1, 3]}}:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
array:filter(
 
array:filter(
 
   array { 0, 1, -2, 3, -4 },
 
   array { 0, 1, -2, 3, -4 },
 
   function($i) { $i > 0 }
 
   function($i) { $i > 0 }
 
)
 
)
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 218: Line 250:
 
| '''Examples'''
 
| '''Examples'''
 
|The following query returns {{Code|55}} (the sum of the integers 1 to 10):
 
|The following query returns {{Code|55}} (the sum of the integers 1 to 10):
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
array:fold-left(
 
array:fold-left(
 
   array { 1 to 10 },
 
   array { 1 to 10 },
Line 224: Line 256:
 
   function($a, $b) { $a + $b }
 
   function($a, $b) { $a + $b }
 
)
 
)
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 238: Line 270:
 
| '''Examples'''
 
| '''Examples'''
 
|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:
 
|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
array {
 
array {
 
   array:fold-right(
 
   array:fold-right(
Line 246: Line 278:
 
   )
 
   )
 
}
 
}
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
Line 260: Line 292:
 
| '''Examples'''
 
| '''Examples'''
 
|The following query returns the array {{Code|[5, 7, 9]}}:
 
|The following query returns the array {{Code|[5, 7, 9]}}:
<pre class="brush:xquery">
+
<syntaxhighlight lang="xquery">
 
array:for-each-pair(
 
array:for-each-pair(
 
   array { 1 to 3 },
 
   array { 1 to 3 },
Line 266: Line 298:
 
   function($a + $b) { $a + $b }
 
   function($a + $b) { $a + $b }
 
)
 
)
</pre>
+
</syntaxhighlight>
 
|}
 
|}
  
==array:serialize==
+
==array:sort==
  
 
{| width='100%'
 
{| width='100%'
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|map:serialize|$input as map(*)|xs:string}}<br/>
+
|{{Func|array:sort|$array as array(*)|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string?|array(*)}}<br/>{{Func|array:sort|$array as array(*), $collation as xs:string?, $key as function(item()*) as xs:anyAtomicType*|array(*)}}<br/>
 
|-
 
|-
 
| '''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.
 
|-
 
|-
 
| '''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 296: Line 331:
 
|}
 
|}
  
[[Category:XQuery]]
+
=Changelog=
 +
 
 +
;Version 8.6
 +
* Updated: [[#array:put|array:put]] collation argument was inserted between first and second argument.
  
=Changelog=
+
;Version 8.5
 +
* Added: [[#array:put|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:40, 17 February 2020

This XQuery Module contains functions for manipulating arrays, which has been introduced with XQuery 3.1.

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:size[edit]

Signatures array:size($input 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:get[edit]

Signatures 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:append[edit]

Signatures array:append($array as array(*), $member as item()*) as array(*)
Summary Returns a copy of $array with a new $member attached.
Examples
  • array:append([], 'member1') returns the array ["member1"].

array:subarray[edit]

Signatures array:subarray($array as array(*), $position as xs:integer) as array(*)
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:put[edit]

Signatures 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]

Signatures 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:insert-before[edit]

Signatures array:insert-before($array as array(*), $position as xs:integer, $member as item()*) as array(*)
Summary Returns a copy of $array with one new $member at the specified $position. Setting $position to the value array:size($array) + 1 yields the same result as array:append($array, $insert).
Errors FOAY0001: $position is not in the range 1 to array:size($array) + 1 inclusive.
Examples
  • array:insert-before(["a"], 1, "b") returns the array ["b", "a"].

array:head[edit]

Signatures 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:tail[edit]

Signatures 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]

Signatures 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:join[edit]

Signatures 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:flatten[edit]

Signatures 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:for-each[edit]

Signatures array:for-each($array as array(*), $function as function(item()*) as item()*) as array(*)
Summary Returns a new array, in which each member is computed by applying $function 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:filter[edit]

Signatures array:filter($array as array(*), $function as function(item()*) as xs:boolean) as array(*)
Summary Returns a new array with those members of $array for which $function 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:fold-left[edit]

Signatures array:fold-left($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
Summary Evaluates the supplied $function cumulatively on successive members of the supplied $array from left to right and using $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]

Signatures array:fold-right($array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*) as item()*
Summary Evaluates the supplied $function cumulatively on successive members of the supplied $array from right to left and using $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:for-each-pair[edit]

Signatures array:for-each-pair($array1 as array(*), $array2 as array(*), $function as function(item()*) as item()*) as array(*)
Summary Returns a new array obtained by evaluating the supplied $function 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:sort[edit]

Signatures array:sort($array as array(*)) as array(*)
array:sort($array as array(*), $collation as xs:string?) as array(*)
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 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.