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 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')` Result: `[ 'member1' ]`

`array:build`

Signature

Signature	array:build( $input as item(), $action as fn(item(), 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(), 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(item()) 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( $items as item()* ) as item()*
Summary	Recursively flattens all arrays that occur in `$items`.
Examples	`array:flatten([ 'a', 'b' ])` Result: `'a', 'b'` `array:flatten([ 1, [ 2, 3 ], 4 ])` Result: `1, 2, 3, 4`

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

Summary Recursively flattens all arrays that occur in $items.

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(), $zero as item(), $action as fn(item(), item(), xs:integer) as item()* ) as item()*
Summary	Evaluates the `$action` cumulatively on successive members of `$array` from left to right, and uses `$zero` 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(), $zero as item(), $action as fn(item(), item(), xs:integer) as item()* ) as item()*
Summary	Evaluates `$action` cumulatively on successive members of `$array` from right to left, and uses `$zero` 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 { 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(item(), 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(item(), item(), 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(item()*, item()*, 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`

Updated: Default parameter added.

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 extends beyonds 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 extends beyonds 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 xs:anyAtomicType, $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(item(), 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(item()*, 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`

Added: New function.

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`

Updated: $separator parameter added.

Signature

Signature	array:join( $arrays as array(), $separator as array()? := () ) as array()
Summary	Concatenates the contents of several `$arrays` into a single array. If a `$separator` is supplied, its members are inserted before the members of the second and the following arrays.
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 { 1 to 3 } => array:split() => array:join([ () ])` Result: `[ 1, (), 2, (), 3 ]`

array:join(
  $arrays     as array(*)*,
  $separator  as array(*)?  := ()
) as array(*)

Summary Concatenates the contents of several $arrays into a single array. If a $separator is supplied, its members are inserted before the members of the second and the following arrays.

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 { 1 to 3 }
=> array:split()
=> array:join([ () ])

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

`array:members`

Added: New function.

Signature

Signature	array:members( $arrays 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:join([1 to 3]` Result: `{ 'value': (1, 2) }` `array:members(array { 1 to 2 })` Result: `{ 'value': 1 }, { 'value': 2 }`

array:members(
  $arrays  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:join([1 to 3]

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

array:members(array { 1 to 2 })

Result: { 'value': 1 }, { 'value': 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 extends beyonds 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 extends beyonds 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` defined 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 defined 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`

Updated: Reverted to 3.1 behavior

Signature

Signature	array:sort( $array as array(), $collation as xs:string? := fn:default-collation(), $key as fn($item 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, which will be applied on each sort items. The members resulting from the sort key will be sorted using 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 ], keys := fn($n) { -$n })` Result: `[ 3, 2, 1 ]`

array:sort(
  $array      as array(*),
  $collation  as xs:string?                                := fn:default-collation(),
  $key        as fn($item 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, which will be applied on each sort items. The members resulting from the sort key will be sorted using 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 ], keys := fn($n) { -$n })

Result: [ 3, 2, 1 ]

`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(*),
  $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`	The specified index extends beyonds 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 extends beyonds 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 extends beyonds the bounds of an array.

Examples

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

Result: [ 'a', 'b' ]

Errors

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

Changelog

Version 12.0

Added: array:items, array:members.
Updated: array:get: Default parameter added.
Updated: array:join

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

Updated: array:put collation argument was inserted between first and second argument.

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