|
|
| Line 486: |
Line 486: |
| | * <code>array:join((["a", "b"], ["c", "d"], [ ]))</code> returns the array {{Code|["a", "b", "c", "d"]}}. | | * <code>array:join((["a", "b"], ["c", "d"], [ ]))</code> returns the array {{Code|["a", "b", "c", "d"]}}. |
| | * <code>array:join((["a", "b"], ["c", "d"], [["e", "f"]]))</code> returns the array {{Code|["a", "b", "c", "d", ["e", "f"]]}}. | | * <code>array:join((["a", "b"], ["c", "d"], [["e", "f"]]))</code> returns the array {{Code|["a", "b", "c", "d", ["e", "f"]]}}. |
| | + | |} |
| | + | |
| | + | ==array:members== |
| | + | |
| | + | {| width='100%' |
| | + | | width='120' | '''Signature''' |
| | + | |<pre>array:members( |
| | + | $array as array(*) |
| | + | ) as record(value as item()*)* |
| | + | </pre> |
| | + | |- valign="top" |
| | + | | '''Summary''' |
| | + | | Delivers the contents of an {{Code|$array}} as a sequence of value records. |
| | + | |- valign="top" |
| | + | | '''Examples''' |
| | + | | |
| | + | <ul> |
| | + | <li><code>array:members([])</code> returns {{Code|()}}.</li> |
| | + | <li><code>array:members([1 to 5])?value</code> returns {{Code|(1, 2, 3, 4, 5)}}.</li> |
| | + | <li><code>array:members([(1,1), (2,4), (3,9), (4,16), (5,25)]) ! sum(?value)</code> returns {{Code|(2, 6, 12, 20, 30)}}.</li> |
| | + | <li><pre>let $array := [ "any array" ] |
| | + | return deep-equal( |
| | + | $array, |
| | + | array:of-members(array:members($array)) |
| | + | )</pre> returns {{Code|true()}}</li> |
| | + | </ul> |
| | |} | | |} |
| | | | |
This XQuery Module contains functions for manipulating arrays, which has been introduced with XQuery 3.1 and extended with XQuery 4.0.
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:append
| Signature
|
array:append(
$array as array(*),
$member as item()*
) as array(*)
|
| Summary
|
Returns a copy of $array with $member attached.
|
| Examples
|
array:append([], 'member1') returns the array ["member1"].
|
array:build
| Signature
|
array:build(
$input as item()*,
$action as function(item()) as item()* := fn:identity#1
) as array(*)
|
| Summary
|
Returns an $array obtained by evaluating the supplied function $action once for each item in the $input sequence.
|
| Examples
|
-
array:build(1 to 5)
returns
[1,2,3,4,5]
-
array:build(1 to 5, function { 2 * . })
returns
[2,4,6,8,10]
-
array:build(1 to 5, function { 1 to . })
returns
[1,(1,2),(1,2,3),(1,2,3,4),(1,2,3,4,5)]
-
array:build(1 to 5, function { array { 1 to . } })
returns
[[1],[1,2],[1,2,3],[1,2,3,4],[1,2,3,4,5]]
-
array:build(("red", "green", "blue"), characters#1)
returns
[("r","e","d"),("g","r","e","e","n"),("b","l","u","e")]
|
array:empty
| Signature
|
array:empty(
$array as array(*)
) as xs:boolean
|
| Summary
|
Returns true if the supplied $array contains no members.
|
| Examples
|
-
array:empty(["a", "b", "c"])
returns
false()
-
array:empty([])
returns
true()
-
array:empty([[]])
returns
false()
-
array:empty([()])
returns
false()
|
array:exists
| Signature
|
array:exists(
$array as array(*)
) as xs:boolean
|
| Summary
|
Returns true if the supplied $array contains one or more members.
|
| Examples
|
-
array:exists(["a", "b", "c"])
returns
true()
-
array:exists([])
returns
false()
-
array:exists([[]])
returns
true()
-
array:exists([()])
returns
true()
|
array:filter
| Signature
|
array:filter(
$array as array(*),
$predicate as function(item()*) as xs:boolean
) as array(*)
|
| Summary
|
Returns a new array with those members of $array for which $predicate returns true.
|
| Examples
|
The following query returns the array [0, 1, 3]:
<syntaxhighlight lang="xquery">
array:filter(
array { 0, 1, -2, 3, -4 },
function($i) { $i > 0 }
)
</syntaxhighlight>
|
array:flatten
| Signature
|
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:fold-left
| Signature
|
array:fold-left(
$array as array(*),
$zero as item()*,
$action as function(item()*, item()*) as item()*
) as item()*
|
| Summary
|
Evaluates the supplied $action cumulatively on successive members of the supplied $array from left to right, and uses $zero as first argument.
|
| Examples
|
The following query returns 55 (the sum of the integers 1 to 10):
<syntaxhighlight lang="xquery">
array:fold-left(
array { 1 to 10 },
0,
function($a, $b) { $a + $b }
)
</syntaxhighlight>
|
array:fold-right
| Signature
|
array:fold-right(
$array as array(*),
$zero as item()*,
$action as function(item()*, item()*) as item()*
) as item()*
|
| Summary
|
Evaluates the supplied $action cumulatively on successive members of the supplied $array from right to left, and uses $zero as first argument.
|
| Examples
|
The following query is equivalent to the expression array:reverse(array { 1 to 5 }):
<syntaxhighlight lang="xquery">
array {
array:fold-right(
array { 1 to 5 },
(),
function($a, $b) { $b, $a }
)
}
</syntaxhighlight>
|
| Signature
|
array:foot(
$array as array(*)
) as item()*
|
| Summary
|
Returns the last member of an array, that is $array(array:size($array)).
|
| Examples
|
-
array:foot([5, 6, 7, 8])
returns
8
-
array:foot([["a", "b"], ["c", "d"]])
returns
["c","d"]
-
array:foot([("a", "b"), ("c", "d")])
returns 2 results
"c" and "d"
|
array:for-each
| Signature
|
array:for-each(
$array as array(*),
$action as function(item()*) as item()*
) as array(*)
|
| Summary
|
Returns a new array, in which each member is computed by applying $action to the corresponding member of $array.
|
| Examples
|
The following query returns the array [2, 3, 4, 5, 6]:
<syntaxhighlight lang="xquery">
array:for-each(
array { 1 to 5 },
function($i) { $i + 1}
)
</syntaxhighlight>
|
array:for-each-pair
| Signature
|
array:for-each-pair(
$array1 as array(*),
$array2 as array(*),
$action as function(item()*) as item()*
) as array(*)
|
| Summary
|
Returns a new array obtained by evaluating the supplied $action for each pair of members at the same position in $array1 and $array2.
|
| Examples
|
The following query returns the array [5, 7, 9]:
<syntaxhighlight lang="xquery">
array:for-each-pair(
array { 1 to 3 },
array { 4 to 6 },
function($a + $b) { $a + $b }
)
</syntaxhighlight>
|
array:get
| Signature
|
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:head
| Signature
|
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:index-where
| Signature
|
array:index-where(
$array as array(*),
$predicate as function(item()*, xs:integer) as xs:boolean
) as xs:integer*
|
| Summary
|
Returns the position in an input $array of members that match a supplied $predicate.
|
| Examples
|
-
array:index-where([0, (), 4, 9], boolean#1)
returns
()
-
array:index-where([0, (), 4, 9], boolean#1)
returns
(3, 4)
-
array:index-where(
array { 1 to 10 },
function {. mod 2 = 0 }
)
returns
(2, 4, 6, 8, 10)
-
array:index-where(
[ "January", "February", "March", "April",
"May", "June", "July", "August", "September",
"October", "November", "December" ],
contains(?, "r")
) returns (1, 2, 3, 4, 9, 10, 11, 12)
-
array:index-where(
[(1, 2, 3), (4, 5, 6), (7, 8)],
function($m) { count($m) = 3 }
) returns (1, 2)
-
array:index-where(
[ 1, 8, 2, 7, 3 ],
fn($member, $pos) { $member < 5 and $pos > 2 }
) returns (3, 5)
|
array:insert-before
| Signature
|
array:insert-before(
$array as array(*),
$position as xs:integer,
$member as item()*
) as array(*)
|
| Summary
|
Returns an array containing all the members of the supplied $array, with one additional $member at a specified $position.
|
| Examples
|
-
array:insert-before(
["a", "b", "c", "d"],
3,
("x", "y")
)
returns ["a", "b", ("x", "y"), "c", "d"]
-
array:insert-before(
["a", "b", "c", "d"],
5,
("x", "y")
)
returns ["a", "b", "c", "d", ("x", "y")]
-
array:insert-before(
["a", "b", "c", "d"],
3,
["x", "y"]
)
returns ["a", "b", ["x", "y"], "c", "d"]
|
array:join
| Signature
|
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:join((["a", "b"], ["c", "d"])) returns the array ["a", "b", "c", "d"].array:join((["a", "b"], ["c", "d"], [ ])) returns the array ["a", "b", "c", "d"].array:join((["a", "b"], ["c", "d"], "e", "f")) returns the array ["a", "b", "c", "d", ["e", "f"]].
|
array:members
| Signature
|
array:members(
$array as array(*)
) as record(value as item()*)*
|
| Summary
|
Delivers the contents of an $array as a sequence of value records.
|
| Examples
|
|
array:size
| Signature
|
array:size(
$array 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:subarray
| Signature
|
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
| Signature
|
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
| Signature
|
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:tail
| Signature
|
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
| Signature
|
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:sort
| Signature
|
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 11.0
- 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.
