Array Module

From BaseX Documentation

(Difference between revisions)
Jump to: navigation, search
 
(34 intermediate revisions 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}} 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 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='100%'
| width='120' | '''Signatures'''
| width='120' | '''Signatures'''
-
|{{Func|array:for-each-member|$array as array(*), $function as function(item()*) as item()*|array(*)}}
+
|{{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='120' | '''Signatures'''
 +
|{{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 252: 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 278: Line 329:
|The specified length is less than zero.
|The specified length is less than zero.
|}
|}
-
 
-
[[Category:XQuery]]
 
=Changelog=
=Changelog=
-
Introduced with Version 8.0.
+
;Version 8.6
 +
* Updated: [[#array:sort|array:put]] collation argument was inserted between first and second argument.
-
[[Category:XQuery]]
+
;Version 8.5
 +
* Added: [[#array:put|array:put]]
 +
 
 +
;Version 8.4
 +
* Removed: array:serialize (use fn:serialize instead)
 +
 
 +
Introduced with Version 8.0.

Latest revision as of 09:39, 27 September 2018

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

Contents

[edit] 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.

[edit] Functions

[edit] 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.

[edit] 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.

[edit] 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"].

[edit] 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"].

[edit] 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"].

[edit] 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 [].

[edit] 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"].

[edit] 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"].

[edit] 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"].

[edit] 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].

[edit] 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].

[edit] 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.

[edit] 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}
)

[edit] 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 }
)

[edit] 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 }
)

[edit] 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 }
  )
}

[edit] 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 }
)

[edit] 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)

[edit] Errors

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

[edit] Changelog

Version 8.6
Version 8.5
Version 8.4

Introduced with Version 8.0.

Personal tools
Namespaces
Variants
Actions
Navigation
Print/export