Main Page » XQuery » Functions » Array Functions

Array Functions

This module provides functions for manipulating arrays. It was introduced with XQuery 3.1 and extended with XQuery 4.0. All functions are described in detail in the XQuery Functions and Operators specification.

Conventions

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

Functions

`array:append`

Signature	array:append( $array as array(), $member as item()) as array(*)
Summary	Returns a copy of `$array` with `$member` appended.
Examples	`array:append([], 'member1')` Result: `[ 'member1' ]`

`array:build`

Signature

Signature	array:build( $input as item(), $action as fn($item as item(), $pos as xs:integer) as item() := fn:identity#1) as array(*)
Summary	Builds an array by evaluating `$action` for each item in the `$input` sequence.
Examples	`array:build(1 to 3)` Result: `[ 1, 2, 3 ]` `array:build(1 to 3, fn { 1 to . })` Result: `[ 1, (1, 2), (1, 2, 3) ]` `array:build(('one', 'two'), characters#1)` Result: `[ ('o', 'n', 'e'), ('t', 'w', 'o') ]`

array:build(  $input   as item()*,  $action  as fn($item as item(), $pos as xs:integer) as item()*  := fn:identity#1) as array(*)

Summary Builds an array by evaluating $action for each item in the $input sequence.

Examples

array:build(1 to 3)

Result: [ 1, 2, 3 ]

array:build(1 to 3, fn { 1 to . })

Result: [ 1, (1, 2), (1, 2, 3) ]

array:build(('one', 'two'), characters#1)

Result: [ ('o', 'n', 'e'), ('t', 'w', 'o') ]

`array:empty`

Signature

Signature	array:empty( $array as array(*)) as xs:boolean
Summary	Returns `true` if `$array` contains no members.
Examples	`array:empty([ 1, 2 ])` Result: `false()` `array:empty([])` Result: `true()` `array:empty([ () ])` Result: `false()`

array:empty(  $array  as array(*)) as xs:boolean

Summary Returns true if $array contains no members.

Examples

array:empty([ 1, 2 ])

Result: false()

array:empty([])

Result: true()

array:empty([ () ])

Result: false()

`array:filter`

Signature	array:filter( $array as array(), $predicate as fn($member as item(), $pos as xs:integer) as xs:boolean?) as array(*)
Summary	Returns a new array with those members of `$array` for which `$predicate` returns `true`.
Examples	`array:filter( array { 0, 1, -2, 3, -4 }, fn($i) { $i > 0 } )` Result: `[ 1, 3 ]`

`array:flatten`

Signature

Signature	array:flatten( $input as item()) as item()
Summary	Recursively flattens all arrays that occur in `$input`.
Examples	`array:flatten([ 'a', 'b' ])` Result: `'a', 'b'` `array:flatten([ 1, [ 2, 3 ], 4 ])` Result: `1, 2, 3, 4`

array:flatten(  $input  as item()*) as item()*

Summary Recursively flattens all arrays that occur in $input.

Examples

array:flatten([ 'a', 'b' ])

Result: 'a', 'b'

array:flatten([ 1, [ 2, 3 ], 4 ])

Result: 1, 2, 3, 4

`array:fold-left`

Signature	array:fold-left( $array as array(), $init as item(), $action as fn($acc as item(), $member as item(), $pos as xs:integer) as item()) as item()
Summary	Evaluates the `$action` cumulatively on successive members of `$array` from left to right, and uses `$init` as first argument. Note: Contrary to the official specification, the current position of the iteration can be retrieved via the third parameter of the higher-order function argument.
Examples	`array:fold-left( array { 1 to 10 }, 0, fn($a, $b) { $a + $b } )` Result: `55`. Computes the sum of the integers `1` to `10`.

`array:fold-right`

Signature	array:fold-right( $array as array(), $init as item(), $action as fn($member as item(), $acc as item(), $pos as xs:integer) as item()) as item()
Summary	Evaluates `$action` cumulatively on successive members of `$array` from right to left, and uses `$init` as the initial accumulator (the second argument of `$action`). Note: Contrary to the official specification, the current position of the iteration can be retrieved via the third parameter of the higher-order function argument.
Examples	`array { array:fold-right( array { 1 to 5 }, (), fn($a, $b) { $b, $a } ) }` The following query is equivalent to the expression `array:reverse(array { 1 to 5 })`.

`array:foot`

Signature

Signature	array:foot( $array as array()) as item()
Summary	Returns the last member of `$array`.
Examples	`array:foot([ 1, 2, 3 ])` Result: `3` `array:foot([ ('a', 'b'), ('c', 'd') ])` Result: `'c', 'd'`

array:foot(  $array  as array(*)) as item()*

Summary Returns the last member of $array.

Examples

array:foot([ 1, 2, 3 ])

Result: 3

array:foot([ ('a', 'b'), ('c', 'd') ])

Result: 'c', 'd'

`array:for-each`

Signature	array:for-each( $array as array(), $action as fn($member as item(), $pos as xs:integer) as item()) as array()
Summary	Creates a new array, in which each member is computed by applying `$action` to the corresponding member of `$array`.
Examples	`array:for-each( array { 1 to 5 }, fn($i) { $i + 1 } )` Result: `[ 2, 3, 4, 5, 6 ]`

`array:for-each-pair`

Signature

Signature	array:for-each-pair( $array1 as array(), $array2 as array(), $action as fn($member1 as item(), $member2 as item(), $pos as xs:integer) as item()) as array()
Summary	Creates a new array by evaluating `$action` for each pair of members at the same position in `$array1` and `$array2`.
Examples	`array:for-each-pair( array { 1 to 3 }, array { 4 to 6 }, fn($a, $b) { $a + $b } )` Result: `[ 5, 7, 9 ]`

array:for-each-pair(  $array1  as array(*),  $array2  as array(*),  $action  as fn($member1 as item()*, $member2 as item()*, $pos as xs:integer) as item()*) as array(*)

Summary Creates a new array by evaluating $action for each pair of members at the same position in $array1 and $array2.

Examples

array:for-each-pair(
  array { 1 to 3 },
  array { 4 to 6 },
  fn($a, $b) { $a + $b }
)

Result: [ 5, 7, 9 ]

`array:get`

Signature

array:get(  $array     as array(*),  $position  as xs:integer,  $default   as item()*  := ()) as item()*

Summary Returns the member of $array at the specified $position. If the specified member does not exist, an error is raised, or (if specified) the value of $default is returned.

Errors

FOAY0001 The specified index lies outside the bounds of an array.

Examples

array:get(array { reverse(1 to 5) }, 5)

Result: 1

array:get([ 1, 2, 3 ], 4, 'unknown')

Result: 'unknown'

`array:head`

Signature

array:head(  $array  as array(*)) as item()*

Summary Returns the first member of $array.

Errors

FOAY0001 The specified index lies outside the bounds of an array.

Examples

array:head([ 'a', 'b' ])

Result: 'a'

array:head([ [ 'a', 'b' ], [ 'c', 'd' ] ])

Result: [ 'a', 'b' ]

`array:index-of`

Signature	array:index-of( $array as array(), $target as item(), $collation as xs:string? := fn:default-collation()) as xs:integer*
Summary	Returns the positions of the members of `$array` that match `$target`.
Examples	`array:index-of([ 1, 3, 2, 3 ], 3)` Result: `2, 4`

`array:index-where`

Signature

Signature	array:index-where( $array as array(), $predicate as fn($member as item(), $pos as xs:integer) as xs:boolean?) as xs:integer*
Summary	Returns the positions of all members of `$array` that match the `$predicate` function.
Examples	`array:index-where([ (), 1, (2, 3) ], fn($member) { count($member) = 2 })` Result: `3` `array:index-where(array { 1 to 5 }, fn { . mod 2 = 0 })` Result: `2, 4`

array:index-where(  $array      as array(*),  $predicate  as fn($member as item()*, $pos as xs:integer) as xs:boolean?) as xs:integer*

Summary Returns the positions of all members of $array that match the $predicate function.

Examples

array:index-where([ (), 1, (2, 3) ], fn($member) { count($member) = 2 })

Result: 3

array:index-where(array { 1 to 5 }, fn { . mod 2 = 0 })

Result: 2, 4

`array:insert-before`

Signature	array:insert-before( $array as array(), $position as xs:integer, $member as item()) as array(*)
Summary	Returns an array with the members of `$array` and an additional `$member` at a specified `$position`.
Examples	`array:insert-before([ 'a', 'b' ], 2, ('x', 'y'))` Result: `[ 'a', ('x', 'y'), 'b' ]`

`array:items`

Signature	array:items( $array as array()) as item()
Summary	Returns a sequence with all the values of `$array`.
Examples	`array:items([ (), 1, (2, 3) ])` Result: `1, 2, 3`

`array:join`

Removed: $separator parameter.

Signature

Signature	array:join( $arrays as array()) as array(*)
Summary	Concatenates the members of several `$arrays` into a single array.
Examples	`array:join(())` Result: `[]` `array:join((1 to 3) ! array { . })` Result: `[ 1, 2, 3 ]` `array:join(([ 'a', 'b' ], [], [ 'c', 'd' ]))` Result: `[ 'a', 'b', 'c', 'd' ]`

array:join(  $arrays  as array(*)*) as array(*)

Summary Concatenates the members of several $arrays into a single array.

Examples

array:join(())

Result: []

array:join((1 to 3) ! array { . })

Result: [ 1, 2, 3 ]

array:join(([ 'a', 'b' ], [], [ 'c', 'd' ]))

Result: [ 'a', 'b', 'c', 'd' ]

`array:members`

Signature

Signature	array:members( $array as array()) as record(value as item())*
Summary	Returns the members of an array as a sequence of value records.
Examples	`array:members([])` Result: `()` `array:members([1 to 2])` Result: `{ 'value': (1, 2) }` `array:members(array { 1 to 2 })` Result: `{ 'value': 1 }, { 'value': 2 }`

array:members(  $array  as array(*)) as record(value as item()*)*

Summary Returns the members of an array as a sequence of value records.

Examples

array:members([])

Result: ()

array:members([1 to 2])

Result: { 'value': (1, 2) }

array:members(array { 1 to 2 })

Result: { 'value': 1 }, { 'value': 2 }

`array:of-members`

Signature

Signature	array:of-members( $input as record(value as item())) as array(*)
Summary	Creates an array from a sequence of value records. The function is the inverse of `array:members`.
Examples	`array:of-members(())` Result: `[]` `array:of-members({ 'value': (1, 2) })` Result: `[ (1, 2) ]` `array:of-members(array:members([ 1, 2 ]))` Result: `[ 1, 2 ]`

array:of-members(  $input  as record(value as item()*)*) as array(*)

Summary Creates an array from a sequence of value records. The function is the inverse of array:members.

Examples

array:of-members(())

Result: []

array:of-members({ 'value': (1, 2) })

Result: [ (1, 2) ]

array:of-members(array:members([ 1, 2 ]))

Result: [ 1, 2 ]

`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.

Errors

FOAY0001 The specified index lies outside the bounds of an array.

Examples

array:put([ 'a', 'b', 'c' ], 2, 'd')

Result: [ '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 The specified index lies outside the bounds of an array.

Examples

array:remove([ 'a', 'b' ], 1)

Result: [ 'b' ]

`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 })` Result: `[ 3, 2, 1 ]`

`array:size`

Signature

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, `fn:count` when applied to an array always returns `1`.
Examples	`array:size(array { 1 to 3 })` Result: `3` `array:size([ 1 to 3 ])` Returns `1`, because the array contains a single sequence with 3 integers.

array:size(  $array  as array(*)) as xs:integer

Summary Returns the number of members in $array. Note that because an array is an item, fn:count when applied to an array always returns 1.

Examples

array:size(array { 1 to 3 })

Result: 3

array:size([ 1 to 3 ])

Returns 1, because the array contains a single sequence with 3 integers.

`array:slice`

Signature

Signature	array:slice( $array as array(), $start as xs:integer? := (), $end as xs:integer? := (), $step as xs:integer? := ()) as array()
Summary	Returns selected members of an `$array` based on their position: If `$start` is supplied, returns the member at this position first. If `$end` is supplied, returns the member at this position last. `$step` defines how the position counter is incremented or decremented.
Examples	`array:slice([ 1, 3, 5, 7 ], 2, 3)` Result: `[ 3, 5 ]` `array:slice([ 1, 3, 5, 7 ], 3, 2, -1)` Result: `[ 5, 3 ]` `array:slice([ 1, 3, 5, 7 ], end := 3)` Result: `[ 1, 3, 5 ]` `array:slice([ 1, 3, 5, 7 ], step := 2)` Result: `[ 1, 5 ]`

array:slice(  $array  as array(*),  $start  as xs:integer?  := (),  $end    as xs:integer?  := (),  $step   as xs:integer?  := ()) as array(*)

Summary

Returns selected members of an $array based on their position:

If $start is supplied, returns the member at this position first.
If $end is supplied, returns the member at this position last.
$step defines how the position counter is incremented or decremented.

Examples

array:slice([ 1, 3, 5, 7 ], 2, 3)

Result: [ 3, 5 ]

array:slice([ 1, 3, 5, 7 ], 3, 2, -1)

Result: [ 5, 3 ]

array:slice([ 1, 3, 5, 7 ], end := 3)

Result: [ 1, 3, 5 ]

array:slice([ 1, 3, 5, 7 ], step := 2)

Result: [ 1, 5 ]

`array:sort`

Signature

Signature	array:sort( $array as array(), $collation as xs:string? := fn:default-collation(), $key as fn($member as item()) as xs:anyAtomicType* := fn:data#1) as array(*)
Summary	Returns a new array with sorted `$array` members. A `$collation` and a `$key` can be supplied; the key is applied to each member. The resulting keys are compared with the semantics of the `lt` operator.
Examples	`array:sort(array { reverse(1 to 3) })` Result: `[ 1, 2, 3 ]` `array:sort([ 3, -2, 1 ], (), abs#1)` Result: `[ 1, -2, 3 ]` `array:sort([ 1, 2, 3 ], key := fn($n) { -$n })` Result: `[ 3, 2, 1 ]`

array:sort(  $array      as array(*),  $collation  as xs:string?  := fn:default-collation(),  $key        as fn($member as item()*) as xs:anyAtomicType*  := fn:data#1) as array(*)

Summary Returns a new array with sorted $array members. A $collation and a $key can be supplied; the key is applied to each member. The resulting keys are compared with the semantics of the lt operator.

Examples

array:sort(array { reverse(1 to 3) })

Result: [ 1, 2, 3 ]

array:sort([ 3, -2, 1 ], (), abs#1)

Result: [ 1, -2, 3 ]

array:sort([ 1, 2, 3 ], key := fn($n) { -$n })

Result: [ 3, 2, 1 ]

`array:sort-by`

Added: New function.

Signature

Signature	array:sort-by( $array as array(), $keys as fn:array-sort-key-record) as array(*)
Summary	Returns a new array with sorted `$array` members. Each entry in `$keys` is an instance of `fn:array-sort-key-record`: `record( key as (fn($member as item()) as xs:anyAtomicType)?, collation as xs:string?, order as enum('ascending', 'descending')? )` The `key` function (default: `fn:data#1`) is applied to each member, the optional `collation` is used for string comparisons, and `order` (default: `'ascending'`) controls the sort direction. Keys are applied in sequence. The sort is stable.
Examples	`array:sort-by([ 3, -2, 1 ], { 'key': abs#1 })` Result: `[ 1, -2, 3 ]` `array:sort-by([ 1, 2, 3 ], { 'order': 'descending' })` Result: `[ 3, 2, 1 ]` `let $persons := [ (8, 'Josipa'), (6, 'Jade'), (8, 'Jie') ] return array:sort-by($persons, ( { 'key': fn($p) { $p[1] } }, { 'key': fn($p) { $p[2] } } ))` Result: `[ (6, "Jade"), (8, "Jie"), (8, "Josipa") ]`

array:sort-by(  $array  as array(*),  $keys   as fn:array-sort-key-record*) as array(*)

Summary

Returns a new array with sorted $array members. Each entry in $keys is an instance of fn:array-sort-key-record:

record(
   key        as (fn($member as item()*) as xs:anyAtomicType*)?,
   collation  as xs:string?,
   order      as enum('ascending', 'descending')?
)

The key function (default: fn:data#1) is applied to each member, the optional collation is used for string comparisons, and order (default: 'ascending') controls the sort direction. Keys are applied in sequence. The sort is stable.

Examples

array:sort-by([ 3, -2, 1 ], { 'key': abs#1 })

Result: [ 1, -2, 3 ]

array:sort-by([ 1, 2, 3 ], { 'order': 'descending' })

Result: [ 3, 2, 1 ]

let $persons := [
  (8, 'Josipa'),
  (6, 'Jade'),
  (8, 'Jie')
]
return array:sort-by($persons, (
  { 'key': fn($p) { $p[1] } },
  { 'key': fn($p) { $p[2] } }
))

Result: [ (6, "Jade"), (8, "Jie"), (8, "Josipa") ]

`array:sort-with`

Added: New function.

Signature

Signature	array:sort-with( $array as array(), $comparators as (fn($member1 as item(), $member2 as item()) as xs:integer)+) as array()
Summary	Returns a new array of `$array` with the order induced by the supplied `$comparators`.
Examples	`array:sort-with([ 1, 4, 6, 5, 3 ], compare#2)` Result: `[ 1, 3, 4, 5, 6 ]` `array:sort-with( [ (), (1, 2), 3 ], fn($a, $b) { count($a) - count($b) } )` Result: `[ (), 3, (1, 2) ]` `let $persons := [ (8, 'Josipa'), (6, 'Jade'), (8, 'Jie') ] return array:sort-with($persons, ( fn($a, $b) { compare($a[1], $b[1]) }, fn($a, $b) { compare($a[2], $b[2]) } ))` Result: `[ (6, "Jade"), (8, "Jie"), (8, "Josipa") ]`

array:sort-with(  $array        as array(*),  $comparators  as (fn($member1 as item()*, $member2 as item()*) as xs:integer)+) as array(*)

Summary Returns a new array of $array with the order induced by the supplied $comparators.

Examples

array:sort-with([ 1, 4, 6, 5, 3 ], compare#2)

Result: [ 1, 3, 4, 5, 6 ]

array:sort-with(
  [ (), (1, 2), 3 ],
  fn($a, $b) { count($a) - count($b) }
)

Result: [ (), 3, (1, 2) ]

let $persons := [
  (8, 'Josipa'),
  (6, 'Jade'),
  (8, 'Jie')
]
return array:sort-with($persons, (
  fn($a, $b) { compare($a[1], $b[1]) },
  fn($a, $b) { compare($a[2], $b[2]) }
))

Result: [ (6, "Jade"), (8, "Jie"), (8, "Josipa") ]

`array:split`

Signature

Signature	array:split( $array as array()) as array()*
Summary	Returns the members of `$array` as a sequence of singleton arrays.
Examples	`array:split(array { 1 to 3 })` Result: `[ 1 ], [ 2 ], [ 3 ]` `array:split([ (), 1, (2, 3) ])` Result: `[ () ], [ 1 ], [ (2, 3) ]`

array:split(  $array  as array(*)) as array(*)*

Summary Returns the members of $array as a sequence of singleton arrays.

Examples

array:split(array { 1 to 3 })

Result: [ 1 ], [ 2 ], [ 3 ]

array:split([ (), 1, (2, 3) ])

Result: [ () ], [ 1 ], [ (2, 3) ]

`array:subarray`

Signature

array:subarray(  $array   as array(*),  $start   as xs:integer,  $length  as xs:integer?  := ()) as array(*)

Summary Constructs a new array with $length members of $array beginning from the specified $start 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) - $start + 1.

Errors

`FOAY0001`	The specified index lies outside the bounds of an array.
`FOAY0002`	The specified length is less than zero.

Examples

array:subarray([ 'a', 'b', 'c' ], 2)

Result: [ 'b', 'c' ]

`array:tail`

Signature

array:tail(  $array  as array(*)) as array(*)

Summary Returns a new array with all members except the first from $array.

Errors

FOAY0001 The specified index lies outside the bounds of an array.

Examples

array:tail([ 'a', 'b', 'c' ])

Result: [ 'b', 'c' ]

`array:trunk`

Signature

array:trunk(  $array  as array(*)) as array(*)

Summary Returns a new array with all members except the last from $array.

Errors

FOAY0001 The specified index lies outside the bounds of an array.

Examples

array:trunk([ 'a', 'b', 'c' ])

Result: [ 'a', 'b' ]

Errors

Code	Description
`FOAY0001`	The specified index lies outside the bounds of an array.
`FOAY0002`	The specified length is less than zero.

Changelog

Version 13.0

Added: array:sort-by, array:sort-with.
Removed: array:join: $separator parameter.

Version 12.0

Added: array:items, array:members, array:of-members.
Updated: array:get: Default parameter added.
Updated: array:join: $separator parameter added.

Version 11.0

Added: array:build, array:empty, array:foot, array:index-of, array:index-where, array:slice, array:split, array:trunk
Updated: array:fold-left, array:fold-right, array:for-each, array:for-each-pair, array:sort

Version 8.5

Added: array:put

Version 8.4

Removed: array:serialize (use fn:serialize instead)

Version 8.0

Added: New module added.

⚡Generated with XQuery

`/`	Jump to the search field
`?`	Show this list