Array Module

From BaseX Documentation
Revision as of 21:38, 9 August 2014 by CG (talk | contribs)
Jump to navigation Jump to search

This XQuery Module contains functions for manipulating arrays, which will officially be introduced with XQuery 3.1.
Please note that the functions are subject to change until the specification has reached its final stage.

Conventions

All functions 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 the supplied array. Note that because an array is an item, the fn:count function when applied to an array always returns 1.
Examples
  • array:size([1 to 10]) returns 10.
  • array:size(array { 1 to 10 }) returns 10.

array:append

Signatures array:append($array as array(*), $insert as item()*) as array(*)
Summary Adds one member at the end of the array. The result is an array whose size is array:size($array) + 1, in which all members in positions 1 to array:size($array) are the same as the members in the corresponding position of $array, and the member in position array:size($array) + 1 is $insert.
Examples
  • array:append([], 'member1') returns the array ["member1"].

array:subarray

Signatures array:subarray($array as array(*), $start as xs:integer) as array(*)
array:subarray($array as array(*), $start as xs:integer, $length as xs:integer) as array(*)
Summary Gets an array containing all members from a supplied array starting at a supplied position, up to a specified length.
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) - $start + 1.
Errors FOAY0001:: $start is less than one, or if $start + $length is greater than array:size($array) + 1.
FOAY0002:: $length is less than zero.
Examples
  • array:append(['member1'], 'member2') returns the array ["member1", "member2"].

array:remove

Signatures array:remove($array as array(*), $index as xs:integer) as array(*)
Summary Constructs a new array without the member at the specified $index.
Errors FOAY0001:: $index 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(*), $index as xs:integer, $insert as item()*) as array(*)
Summary Constructs a new array by adding one new member at a specified position. Setting $index to the value array:size($array) + 1 delivers the same result as array:append($array, $insert).
Errors FOAY0001:: $index 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:for-each-member

Signatures array:for-each-member($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-member(
  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 Template:$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(*), $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.

array:fold-right

Signatures array:fold-left($array as array(*), $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.

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:serialize

Signatures map:serialize($input as map(*)) as xs:string
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.
Examples
  • array:serialize([ 1, (2, 3), 4 to 6 ]) returns [1, (2, 3), (4, 5, 6)].

Errors

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

Changelog

Introduced with Version 8.0.