Difference between revisions of "Array Module"

From BaseX Documentation
Jump to navigation Jump to search
(43 intermediate revisions by 2 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.
 +
|}
 +
 +
==array:get==
 +
 +
{| width='100%'
 +
| width='120' | '''Signatures'''
 +
|{{Func|array:get|$array as array(*), $position as xs:integer|item()*}}
 +
|-
 +
| '''Summary'''
 +
| Returns the {{Code|$array}} member at the specified {{Code|$position}}.
 +
|-
 +
| '''Errors'''
 +
|{{Error|FOAY0001|#Errors}} {{Code|$position}} is not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 +
|-
 +
| '''Examples'''
 +
|
 +
* <code>array:get(array { reverse(1 to 5) }, 5)</code> returns the value {{Code|1}}.
 
|}
 
|}
  
Line 41: Line 57:
 
{| width='100%'
 
{| width='100%'
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|array:subarray|$array as array(*), $index as xs:integer|array(*)}}<br/>{{Func|array:subarray|$array as array(*), $index as xs:integer, $length as xs:integer|array(*)}}
+
|{{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(*)}}
 +
|-
 +
| '''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}}.
 +
|-
 +
| '''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'''
 +
|
 +
* <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'''
 
| '''Summary'''
| Constructs a new array with with {{Code|$length}} members of {{Code|$array}} beginning from the specified {{Code|$index}}.<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) - $index + 1}}.
+
| 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'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: {{Code|$index}} is less than one, or if {{Code|$index + $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 not in the range {{Code|1}} to {{Code|array:size($array)}} inclusive.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
 
|
 
|
* <code>array:append(['member1'], 'member2')</code> returns the array {{Code|["member1", "member2"]}}.
+
* <code>array:put(["a", "b", "c"], 2, "d")</code> returns the array {{Code|["a", "d", "c"]}}.
 
|}
 
|}
  
Line 58: 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 75: 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}} delivers 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 98: Line 131:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: The array is empty.
+
|{{Error|FOAY0001|#Errors}} The array is empty.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 116: Line 149:
 
|-
 
|-
 
| '''Errors'''
 
| '''Errors'''
|{{Error|FOAY0001|#Errors}}: The array is empty.
+
|{{Error|FOAY0001|#Errors}} The array is empty.
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 152: Line 185:
 
|}
 
|}
  
==array:for-each-member==
+
==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}}.
 +
|}
 +
 
 +
==array:for-each==
  
 
{| width='100%'
 
{| width='100%'
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|array:for-each-member|$array as array(*), $function as function(item()*) as item()*|array(*)}}
+
|{{Func|array:for-each|$array as array(*), $function as function(item()*) as item()*|array(*)}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
Line 164: Line 212:
 
|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">
 
<pre class="brush:xquery">
array:for-each-member(
+
array:for-each(
 
   array { 1 to 5 },
 
   array { 1 to 5 },
 
   function($i) { $i + 1}
 
   function($i) { $i + 1}
Line 178: Line 226:
 
|-
 
|-
 
| '''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'''
Line 194: Line 242:
 
{| width='100%'
 
{| width='100%'
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|array:fold-left|$array as array(*), $function as function(item()*, item()*) as item()*|item()*}}
+
|{{Func|array:fold-left|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from left to right.
+
| 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.
 +
|-
 +
| '''Examples'''
 +
|The following query returns {{Code|55}} (the sum of the integers 1 to 10):
 +
<pre class="brush:xquery">
 +
array:fold-left(
 +
  array { 1 to 10 },
 +
  0,
 +
  function($a, $b) { $a + $b }
 +
)
 
</pre>
 
</pre>
 
|}
 
|}
Line 205: Line 262:
 
{| width='100%'
 
{| width='100%'
 
| width='120' | '''Signatures'''
 
| width='120' | '''Signatures'''
|{{Func|array:fold-left|$array as array(*), $function as function(item()*, item()*) as item()*|item()*}}
+
|{{Func|array:fold-right|$array as array(*), $zero as item()*, $function as function(item()*, item()*) as item()*|item()*}}
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
| Evaluates the supplied {{Code|$function}} cumulatively on successive members of the supplied {{Code|$array}} from right to left.
+
| 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.
 +
|-
 +
| '''Examples'''
 +
|The following query is equivalent to the expression <code>array:reverse(array { 1 to 5 })</code>:
 +
<pre class="brush:xquery">
 +
array {
 +
  array:fold-right(
 +
    array { 1 to 5 },
 +
    (),
 +
    function($a, $b) { $b, $a }
 +
  )
 +
}
 
</pre>
 
</pre>
 
|}
 
|}
Line 232: Line 300:
 
|}
 
|}
  
==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 259: Line 330:
 
|}
 
|}
  
[[Category:XQuery]]
+
=Changelog=
  
=Changelog=
+
;Version 8.6
 +
* Updated: [[#array:sort|array:put]] collation argument was inserted between first and second argument.
 +
 
 +
;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]]
 

Revision as of 10:39, 27 September 2018

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

Conventions

All functions and errors in this module are assigned to the http://www.w3.org/2005/xpath-functions/array namespace, which is statically bound to the array prefix.

Functions

array:size

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Code Description
FOAY0001 The specified index extends beyonds the bounds of an array.
FOAY0002 The specified length is less than zero.

Changelog

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.