XPath and XQuery Functions and Operators 4.0

15 Processing arrays

Arrays were introduced as a new datatype in XDM 3.1. This section describes functions that operate on arrays.

An array is an additional kind of item. An array of size N is a mapping from the integers (1 to N) to a set of values, called the members of the array, each of which is an arbitrary sequence. Because an array is an item, and therefore a sequence, arrays can be nested.

An array acts as a function from integer positions to associated values, so the function call $array($index) can be used to retrieve the array member at a given position. The function corresponding to the array has the signature function($index as xs:integer) as item()*. The fact that an array is a function item allows it to be passed as an argument to higher-order functions that expect a function item as one of their arguments.

15.2 Functions that operate on arrays

The functions defined in this section use a conventional namespace prefix array, which is assumed to be bound to the namespace URI http://www.w3.org/2005/xpath-functions/array.

As with all other values, arrays are treated as immutable. For example, the array:reverse function returns an array that differs from the supplied array in the order of its members, but the supplied array is not changed by the operation. Two calls on array:reverse with the same argument will return arrays that are indistinguishable from each other; there is no way of asking whether these are “the same array”. Like sequences, arrays have no identity.

All functionality on arrays is defined in terms of two primitives:

The function array:members decomposes an array to a sequence of value records.
The function array:of-members composes an array from a sequence of value records.

A value record here is an item that encapsulates an arbitrary value; the representation chosen for a value record is record(value as item()*), that is, a map containing a single entry whose key is the string "value" and whose value is the encapsulated sequence.

Note that when the required type of an argument to a function such as array:build is an array type, then the coercion rules ensure that a JNode can be supplied in the function call: if the ·content· property of the JNode is an array, then the array is automatically extracted as if by the jnode-content function.

Function	Meaning
`array:append`	Returns an array containing all the members of a supplied array, plus one additional member at the end.
`array:build`	Returns an array obtained by evaluating the supplied function once for each item in the input sequence.
`array:empty`	Returns `true` if the supplied array contains no members.
`array:filter`	Returns an array containing those members of the `$array` for which `$predicate` returns `true`. A return value of `()` is treated as `false`.
`array:flatten`	Replaces any array appearing in a supplied sequence with the members of the array, recursively.
`array:fold-left`	Evaluates the supplied function cumulatively on successive members of the supplied array.
`array:fold-right`	Evaluates the supplied function cumulatively on successive values of the supplied array.
`array:foot`	Returns the last member of an array.
`array:for-each`	Returns an array whose size is the same as `array:size($array)`, in which each member is computed by applying `$action` to the corresponding member of `$array`.
`array:for-each-pair`	Returns an array obtained by evaluating the supplied function once for each pair of members at the same position in the two supplied arrays.
`array:get`	Returns the value at the specified position in the supplied array (counting from 1).
`array:head`	Returns the first member of an array, that is `$array(1)`.
`array:index-of`	Returns a sequence of positive integers giving the positions within the array `$array` of members that are equal to `$target`.
`array:index-where`	Returns the positions in an input array of members that match a supplied predicate.
`array:insert-before`	Returns an array containing all the members of the supplied array, with one additional member at a specified position.
`array:items`	Returns the sequence concatenation of the members of an array.
`array:join`	Concatenates the contents of several arrays into a single array, with an optional separator between adjacent members.
`array:members`	Delivers the contents of an array as a sequence of value records.
`array:of-members`	Constructs an array from the contents of a sequence of value records.
`array:put`	Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value.
`array:remove`	Returns an array containing all the members of the supplied array, except for the members at specified positions.
`array:reverse`	Returns an array containing all the members of a supplied array, but in reverse order.
`array:size`	Returns the number of members in the supplied array.
`array:slice`	Returns an array containing selected members of a supplied input array based on their position.
`array:sort`	Sorts a supplied array, based on the value of a sort key supplied as a function.
`array:sort-by`	Sorts a supplied array, based on the value of a number of sort keys supplied as functions.
`array:sort-with`	Sorts a supplied array, according to the order induced by the supplied comparator functions.
`array:split`	Delivers the contents of an array as a sequence of single-member arrays.
`array:subarray`	Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.
`array:tail`	Returns an array containing all members except the first from a supplied array.
`array:trunk`	Returns an array containing all members except the last from a supplied array.

15.2.9 array:for-each

Changes in 4.0 ⬇ ⬆

The $action callback function now accepts an optional position argument. [Issue 516 PR 828 14 November 2023]

Summary

Returns an array whose size is the same as array:size($array), in which each member is computed by applying $action to the corresponding member of $array.

Signature

`array:for-each`(
`$array`	`as` `array(*)`,
`$action`	`as` `fn(item(), xs:integer) as item()`
) `as` `array(*)`

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

Informally, the function returns an array whose members are obtained by applying the supplied $action function to each member of the input array in turn.

The $action function is called with two arguments: the first is the array member (which in general is an arbitrary sequence), and the second is the 1-based integer position.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression.

array:of-members(
  for-each(array:members($array), 
  fn($member, $pos) {
    { 'value': $action($member, $pos) }
  })
)

array:of-members(
  for-each(array:members($array), 
           fn($member, $pos) {
              { 'value': $action(map:get($member, 'value'), $pos) }
           })
)

Examples

Expression:	array:for-each( [ "A", "B", 1, 2 ], fn($z) { $z instance of xs:integer } )
Result:	[false(), false(), true(), true()]
Expression:	array:for-each( [ "the cat", "sat", "on the mat" ], tokenize#1 )
Result:	[ ("the", "cat"), "sat", ("on", "the", "mat") ]
Expression:	array:for-each( [ [ "the", "cat" ], [ "sat" ], [ "on", "the", "mat" ] ], array:flatten#1 )
Result:	[ ("the", "cat"), "sat", ("on", "the", "mat") ]
Expression:	array:for-each( [ 'one', 'two', 'three' ], fn($member, $pos) { $pos \|\| '. ' \|\| $member } )
Result:	[ "1. one", "2. two", "3. three" ]

XPath and XQuery Functions and Operators 4.0

W3C Editor's Draft 23 February 2026

Abstract

Status of this Document

Dedication

15 Processing arrays

15.2 Functions that operate on arrays

15.2.9 array:for-each