# Array Module

(Difference between revisions)
 Revision as of 20:51, 9 August 2014 (edit)CG (Talk | contribs) (→array:fold-right)← Older edit Revision as of 21:10, 9 August 2014 (edit) (undo)CG (Talk | contribs) Newer edit → Line 198: Line 198: | '''Summary''' | '''Summary''' | 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. | 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): +
+                                                                                    array:fold-left(
+                                                                                    array { 1 to 10 },
+                                                                                    0,
+                                                                                    function(\$a, \$b) { \$a + \$b }
+                                                                                    )
+
|} |} Line 208: Line 218: | '''Summary''' | '''Summary''' | 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. | 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 array:reverse(array { 1 to 5 }: +
+                                                                                    array {
+                                                                                    array:fold-right(array { 1 to 5 }, (), function(\$a, \$b) { \$b, \$a })
+                                                                                    }
+
|} |}

## Revision as of 21:10, 9 August 2014

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 `\$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(*), \$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(*), \$index as xs:integer) as array(*)``array:subarray(\$array as array(*), \$index as xs:integer, \$length as xs:integer) as array(*)` Summary Constructs a new array with with `\$length` members of `\$array` beginning from the specified `\$index`.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) - \$index + 1`. Errors `FOAY0001`:: `\$index` is less than one, or if `\$index + \$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 Returns a copy of `\$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, \$member as item()*) as array(*)` Summary Returns a copy of `\$array` with one new `\$member` at the specified `\$index`. Setting `\$index` to the value `array:size(\$array) + 1` yields 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"]`.

 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(*), \$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: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.