XPath and XQuery Functions and Operators 4.0

17 Maps

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

A map is a kind of item.

[Definition] A map consists of a sequence of entries, also known as key-value pairs. Each entry comprises a key which is an arbitrary atomic item, and an arbitrary sequence called the associated value.

[Definition] Within a map, no two entries have the same key. Two atomic items K1 and K2 are the same key for this purpose if the function call fn:atomic-equal($K1, $K2) returns true.

It is not necessary that all the keys in a map should be of the same type (for example, they can include a mixture of integers and strings).

Maps are immutable, and have no identity separate from their content. For example, the map:remove function returns a map that differs from the supplied map by the omission (typically) of one entry, but the supplied map is not changed by the operation. Two calls on map:remove with the same arguments return maps that are indistinguishable from each other; there is no way of asking whether these are “the same map”.

A map can also be viewed as a function from keys to associated values. To achieve this, a map is also a function item. The function corresponding to the map has the signature function($key as xs:anyAtomicValue) as item()*. Calling the function has the same effect as calling the map:get function: the expression $map($key) returns the same result as get($map, $key). For example, if $books-by-isbn is a map whose keys are ISBNs and whose assocated values are book elements, then the expression $books-by-isbn("0470192747") returns the book element with the given ISBN. The fact that a map 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.

17.4 Functions that Operate on Maps

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

The function call map:get($map, $key) can be used to retrieve the value associated with a given key.

There is no operation to atomize a map or convert it to a string. The function fn:serialize can in some cases be used to produce a JSON representation of a map.

Function	Meaning
`map:build`	Returns a map that typically contains one entry for each item in a supplied input sequence.
`map:contains`	Tests whether a supplied map contains an entry for a given key.
`map:empty`	Returns `true` if the supplied map contains no entries.
`map:entries`	Returns a sequence containing all the key-value pairs present in a map, each represented as a single-entry map.
`map:entry`	Returns a single-entry map that represents a single key-value pair.
`map:filter`	Selects entries from a map, returning a new map.
`map:find`	Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.
`map:for-each`	Applies a supplied function to every entry in a map, returning the sequence concatenation^XP of the results.
`map:get`	Returns the value associated with a supplied key in a given map.
`map:items`	Returns a sequence containing all the values present in a map, in order.
`map:keys`	Returns a sequence containing all the keys present in a map.
`map:keys-where`	Returns a sequence containing selected keys present in a map.
`map:merge`	Returns a map that combines the entries from a number of existing maps.
`map:of-pairs`	Returns a map that combines data from a sequence of key-value pair maps.
`map:pair`	Returns a key-value pair map that represents a single key-value pair.
`map:pairs`	Returns a sequence containing all the key-value pairs present in a map, each represented as a key-value pair map.
`map:put`	Returns a map containing all the contents of the supplied map, but with an additional entry, which replaces any existing entry for the same key.
`map:remove`	Returns a map containing all the entries from a supplied map, except those having a specified key.
`map:replace`	Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.
`map:replace`	Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.
`map:size`	Returns the number of entries in the supplied map.

17.4.19 map:replace

Changes in 4.0 ⬇ ⬆

New in 4.0

Summary

Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.

Signature

`map:replace`(
`$map`	`as` `map(*)`,
`$key`	`as` `xs:anyAtomicType`,
`$action`	`as` `fn($value as item()) as item()`
) `as` `map(*)`

Properties

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

Rules

If the supplied $map contains an existing entry for the supplied $key, then the returned map contains an entry for that $key whose value is obtained by applying the supplied $action to the existing value associated with that key.

Otherwise, the returned map contains an entry for the supplied $key whose value is obtained by applying the supplied $action to an empty sequence.

If there is an existing entry then the new entry replaces the old in its existing position; otherwise it goes at the end. The relative order of other entries in the map is retained.

Formal Equivalent

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

if (map:contains($map, $key)) 
then map:put($map, $key, $action(map:get($map, $key)))
else map:put($map, $key, $action(()))

Examples

Expression:	`map:replace({ 1: "alpha", 2: "beta" }, 1, upper-case#1)`
Result:	{ 1: "ALPHA", 2: "beta" }
Expression:	`map:replace({ 1: "alpha", 2: "beta" }, 3, upper-case#1)`
Result:	{ 1: "alpha", 2: "beta", 3: "" }
Expression:	fold-left( ("a", "b", "c", "a"), {}, fn($map, $key) { map:replace($map, $key, fn($val) { ($val otherwise 0) + 1 }) } )
Result:	{ "a": 2, "b": 1, "c": 1 }

17.4.2017.4.19 map:size

Summary

Returns the number of entries in the supplied map.

Signature

`map:size`(
`$map`	`as` `map(*)`
) `as` `xs:integer`

Properties

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

Rules

The function map:size takes any map as its $map argument and returns the number of entries that are present in the map.

Formal Equivalent

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

count(map:entries($map))

Examples

Expression	Result
`map:size({})`	0
`map:size({ "true": 1, "false": 0 })`	2

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

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

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:replace`	Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value, the new value being computed from the previous value.
`array:replace`	Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value, the new value being computed from the previous value.
`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 number of sort keys supplied as 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.

18.2.22 array:replace

Changes in 4.0 ⬇ ⬆

New in 4.0

Summary

Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value, the new value being computed from the previous value.

Signature

`array:replace`(
`$array`	`as` `array(*)`,
`$position`	`as` `xs:integer`,
`$action`	`as` `fn(item()) as item()`
) `as` `array(*)`

Properties

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

Rules

Informally, the result is an array whose size is array:size($array), in which all members in positions other than $position are the same as the members in the corresponding position of $array, and the member in position $position is the result of applying the $action function to the original value in that position.

Formal Equivalent

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

$array 
=> array:remove($position) 
=> array:insert-before($position, $action(array:get($array, $position)))

Error Conditions

A dynamic error occurs [err:FOAY0001] if $position is not in the range 1 to array:size($array) inclusive.

This error will always occur if $array is empty.

Examples

Expression	Result
array:replace( [ 10, 11, 12 ], 2, fn { . + 10 } )	[ 10, 21, 12 ]
array:replace( [ "a", "b", "c" ], 2, concat(?, "x") )	[ "a", "bx", "c" ]
array:replace( [ ("a", "b"), ("c", "d") ], 2, reverse#1 )	[ ("a", "b"), ("d", "c") ]

Expression

Result

array:replace(
  [ 10, 11, 12 ],
  2,
  fn { . + 10 }
)

[ 10, 21, 12 ]

array:replace(
  [ "a", "b", "c" ],
  2,
  concat(?, "x")
)

[ "a", "bx", "c" ]

array:replace(
  [ ("a", "b"), ("c", "d") ],
  2,
  reverse#1
)

[ ("a", "b"), ("d", "c") ]

18.2.2318.2.22 array:reverse

Summary

Returns an array containing all the members of a supplied array, but in reverse order.

Signature

`array:reverse`(
`$array`	`as` `array(*)`
) `as` `array(*)`

Properties

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

Rules

The function returns an array with the same number of members as $array, but in reverse order.

Formal Equivalent

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

$array 
=> array:members() 
=> reverse() 
=> array:of-members()

Examples

Expression	Result
`array:reverse([ "a", "b", "c", "d" ])`	[ "d", "c", "b", "a" ]
`array:reverse([ ("a", "b"), ("c", "d") ])`	[ ("c", "d"), ("a", "b") ]
`array:reverse([ 1 to 5 ])`	[ (1, 2, 3, 4, 5) ]
`array:reverse([])`	[]

18.2.2418.2.23 array:size

Summary

Returns the number of members in the supplied array.

Signature

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

Properties

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

Rules

The function returns the number of members in the array.

Formal Equivalent

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

count(array:members($array))

Notes

Note that because an array is an item, the fn:count function when applied to an array always returns 1.

Examples

Expression	Result
`array:size([ "a", "b", "c" ])`	3
`array:size([ "a", [ "b", "c" ] ])`	2
`array:size([])`	0
`array:size([ [] ])`	1

18.2.2518.2.24 array:slice

Changes in 4.0 ⬇ ⬆

New in 4.0

Summary

Returns an array containing selected members of a supplied input array based on their position.

Signature

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

Properties

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

Rules

Informally, the array is converted to a sequence, the function fn:slice is applied to this sequence, and the resulting sequence is converted back to an array.

Formal Equivalent

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

$array 
=> array:members() 
=> slice($start, $end, $step) 
=> array:of-members()

Notes

Note that unlike other operations on arrays, there are no out-of-bounds errors for inappropriate values of $start, $end, or $step.

Examples

Variables
let $in := [ 'a', 'b', 'c', 'd', 'e' ]

Expression	Result
`array:slice($in, start := 2, end := 4)`	[ "b", "c", "d" ]
`array:slice($in, start := 2)`	[ "b", "c", "d", "e" ]
`array:slice($in, end := 2)`	[ "a", "b" ]
`array:slice($in, start := 3, end := 3)`	[ "c" ]
`array:slice($in, start := 4, end := 3)`	[ "d", "c" ]
`array:slice($in, start := 2, end := 5, step := 2)`	[ "b", "d" ]
`array:slice($in, start := 5, end := 2, step := -2)`	[ "e", "c" ]
`array:slice($in, start := 2, end := 5, step := -2)`	[]
`array:slice($in, start := 5, end := 2, step := 2)`	[]
`array:slice($in)`	[ "a", "b", "c", "d", "e" ]
`array:slice($in, start := -1)`	[ "e" ]
`array:slice($in, start := -3)`	[ "c", "d", "e" ]
`array:slice($in, end := -2)`	[ "a", "b", "c", "d" ]
`array:slice($in, start := 2, end := -2)`	[ "b", "c", "d" ]
`array:slice($in, start := -2, end := 2)`	[ "d", "c", "b" ]
`array:slice($in, start := -4, end := -2)`	[ "b", "c", "d" ]
`array:slice($in, start := -2, end := -4)`	[ "d", "c", "b" ]
`array:slice($in, start := -4, end := -2, step := 2)`	[ "b", "d" ]
`array:slice($in, start := -2, end := -4, step := -2)`	[ "d", "b" ]
`array:slice([ "a", "b", "c", "d" ], 0)`	[ "a", "b", "c", "d" ]

18.2.2618.2.25 array:sort

Changes in 4.0 ⬇ ⬆

New in 4.0

Summary

Sorts a supplied array, based on the value of a number of sort keys supplied as functions.

Signature

`array:sort`(
`$array`	`as` `array(*)`,
`$collations`	`as` `xs:string*`	`:=` `fn:default-collation()`,
`$keys`	`as` `(fn(item()) as xs:anyAtomicType)*`	`:=` `fn:data#1`,
`$orders`	`as` `enum('ascending', 'descending')*`	`:=` `'ascending'`
) `as` `item()*`

Properties

This function is deterministic, context-dependent, and focus-independent. It depends on collations.

Rules

The result of the function is an array that contains all the members from $input, typically in a different order, the order being defined by the supplied sort key definitions.

A sort key definition has three parts:

A sort key function, which is applied to each member in the input array to determine a sort key value.
A collation, which is used when comparing sort key values that are of type xs:string or xs:untypedAtomic.
An order direction, which is ascending or descending.

The number of sort key definitions is determined by the number of function items supplied in the $keys argument. If the argument is absent or empty, the default is a single sort key definition using the function data#1.

The $nth sort key definition (where $n counts from one (1)) is established as follows:

The sort key function is $keys[$n] otherwise data#1.
The collation is $collations[$n] otherwise $collations[last()] otherwise default-collation(). That is, it is the collation supplied in the corresponding item of the supplied $collations argument; or in its absence, the last entry in $collations; or if $collations is absent or empty, the default collation from the static context of the caller.
The order direction is $orders[$n] otherwise $orders[last()] otherwise "ascending". That is, it is "ascending" or "descending" according to the value of the corresponding item in the supplied $orders argument; or in its absence, the last entry in $orders; or if $orders is absent or empty, then "ascending".

When comparing values of types other than xs:string or xs:untypedAtomic, the corresponding collation is ignored, and no error is reported if the supplied value is not a known or valid collation name. If it is necessary to supply such an ignored value (for example, in the case where a non-string sort key is followed by another sort key that requires a collation) the empty string can be supplied.

The result of the function is defined by reference to the fn:sort function.

Formal Equivalent

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

$array
=> array:members()
=> sort(
  $collations,
  for $key in ($keys otherwise data#1)
  return fn($member as record(value)) as xs:anyAtomicType* {
    $key($member?value)
  },
  $orders
)
=> array:of-members()

Error Conditions

If the set of computed sort keys contains values that are not comparable using the lt operator then the sort operation will fail with a type error ([err:XPTY0004]^XP).

Examples

Expression:	`array:sort([ 1, 4, 6, 5, 3 ])`
Result:	[ 1, 3, 4, 5, 6 ]
Expression:	`array:sort([ 1, 4, 4e0, 6, 5, 3 ], orders := "descending")`
Result:	[ 6, 5, 4, 4e0, 3, 1 ]
Expression:	`array:sort([ 1, -2, 5, 10, -10, 10, 8 ], (), abs#1)`
Result:	[ 1, -2, 5, 8, 10, -10, 10 ]
Expression:	`array:sort([ [ 2, "i" ], [ 1, "e" ], [ 2, "g" ], [ 1, "f" ] ])`
Result:	[ [ 1, "e" ], [ 1, "f" ], [ 2, "g" ], [ 2, "i" ] ]
Expression:	array:sort( [ [ 2, "i" ], [ 1, "e" ], [ 2, "g" ], [ 1, "f" ] ], (), (array:get(?, 1), array:get(?, 2)), ("ascending", "descending") )
Result:	[ [ 1, "f" ], [ 1, "e" ], [ 2, "i" ], [ 2, "g" ]]
To sort an array of strings `$in` using Swedish collation:
let $SWEDISH := collation({ 'lang': 'se' }) return array:sort($in, $SWEDISH)
To sort an array of maps representing employees, using last name as the major sort key and first name as the minor sort key, with the default collation:
array:sort($employees, (), fn($emp) { $emp?name?last, $emp?name?first })

18.2.2718.2.26 array:split

Changes in 4.0 ⬇ ⬆

New in 4.0

Summary

Delivers the contents of an array as a sequence of single-member arrays.

Signature

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

Properties

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

Rules

The members of the array are delivered as a sequence of single-member arrays^DM. Each returned array encapsulates the value of one member of $array.

Formal Equivalent

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

array:for-each($array, fn($member) { [] => array:append($member) })
=> array:items()

Notes

The function call array:split($array) produces the same result as the expression for member $m in $array return [ $m ].

This function is the inverse of array:join.

Examples

Expression:	`array:split([])`
Result:	()
Expression:	`array:split([ () ])`
Result:	[ () ]
Expression:	`array:split([ 1 to 5 ])`
Result:	[ (1, 2, 3, 4, 5) ]
Expression:	array:split( array { 1 to 5 } )
Result:	[ 1 ], [ 2 ], [ 3 ], [ 4 ], [ 5 ]
Expression:	array:split( [ (1, 1), (2, 4), (3, 9), (4, 16), (5, 25) ] ) ! sum(.)
Result:	2, 6, 12, 20, 30
Expression:	let $array := [ "any array" ] return deep-equal( $array, array:join(array:split($array)) )
Result:	true()

18.2.2818.2.27 array:subarray

Changes in 4.0 ⬇ ⬆

Supplying an empty sequence as the value of an optional argument is equivalent to omitting the argument.

Summary

Returns an array containing all members from a supplied array starting at a supplied position, up to a specified length.

Signature

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

Properties

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

Rules

Except in error cases, 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.

Setting the third argument to the empty sequence has the same effect as omitting the argument.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

$array
=> array:members()
=> subsequence($start, $length)
=> array:of-members()

Error Conditions

A dynamic error is raised [err:FOAY0001] if $start is less than one or greater than array:size($array) + 1.

For the three-argument version of the function:

A dynamic error is raised [err:FOAY0002] if $length is less than zero.
A dynamic error is raised [err:FOAY0001] if $start + $length is greater than array:size($array) + 1.

Notes

The value of $start can be equal to array:size($array) + 1 provided that $length is either equal to zero or omitted. In this case the result will be an empty array.

Examples

Expression	Result
`array:subarray([ "a", "b", "c", "d" ], 2)`	[ "b", "c", "d" ]
`array:subarray([ "a", "b", "c", "d" ], 5)`	[]
`array:subarray([ "a", "b", "c", "d" ], 2, 0)`	[]
`array:subarray([ "a", "b", "c", "d" ], 2, 1)`	[ "b" ]
`array:subarray([ "a", "b", "c", "d" ], 2, 2)`	[ "b", "c" ]
`array:subarray([ "a", "b", "c", "d" ], 5, 0)`	[]
`array:subarray([], 1, 0)`	[]

18.2.2918.2.28 array:tail

Summary

Returns an array containing all members except the first from a supplied array.

Signature

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

Properties

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

Rules

The function returns an array containing all members of the supplied array except the first.

Formal Equivalent

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

array:remove($array, 1)

Error Conditions

A dynamic error occurs [err:FOAY0001] if $array is empty.

Notes

If the supplied array contains exactly one member, the result will be an empty array.

Examples

Expression	Result
`array:tail([ 5, 6, 7, 8 ])`	[ 6, 7, 8 ]
`array:tail([ 5 ])`	[]

18.2.3018.2.29 array:trunk

Changes in 4.0 ⬇ ⬆

New in 4.0 [Issue 97 PR 250]

Summary

Returns an array containing all members except the last from a supplied array.

Signature

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

Properties

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

Rules

The function returns an array containing all members of the supplied array except the last.

Formal Equivalent

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

array:remove($array, array:size($array))

Error Conditions

A dynamic error occurs [err:FOAY0001] if $array is empty.

Notes

If the supplied array contains exactly one member, the result will be an empty array.

Examples

Expression	Result
`array:trunk([ 5, 6, 7, 8 ])`	[ 5, 6, 7 ]
`array:trunk([ 5 ])`	[]

G Changes since version 3.1 (Non-Normative)

G.1 Summary of Changes

Use the arrows to browse significant changes since the 3.1 version of this specification.
See 1 Introduction
Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.
See 1 Introduction
PR 1547 1551
New in 4.0
See 2.2.8 fn:siblings
PR 629 803
New in 4.0
See 3.2.2 fn:message
PR 1260 1275
A third argument has been added, providing control over the rounding mode.
See 4.4.4 fn:round
New in 4.0
See 4.4.7 fn:is-NaN
PR 1049 1151
Decimal format parameters can now be supplied directly as a map in the third argument, rather than referencing a format defined in the static context.
See 4.7.2 fn:format-number
PR 1205 1230
New in 4.0
See 4.8.2 math:e
See 4.8.16 math:sinh
See 4.8.17 math:cosh
See 4.8.18 math:tanh
The 3.1 specification suggested that every value in the result range should have the same chance of being chosen. This has been corrected to say that the distribution should be arithmetically uniform (because there are as many xs:double values between 0.01 and 0.1 as there are between 0.1 and 1.0).
See 4.9.2 fn:random-number-generator
PR 261 306 993
New in 4.0
See 5.4.1 fn:char
New in 4.0
See 5.4.2 fn:characters
PR 937 995 1190
New in 4.0
See 5.4.13 fn:hash
The $action argument is new in 4.0.
See 5.6.4 fn:replace
New in 4.0
See 6.6.2 fn:parse-uri
PR 1423 1413
New in 4.0
See 6.6.3 fn:build-uri
New in 4.0
See 10.2.6 fn:in-scope-namespaces
Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.
See 10.2.7 fn:in-scope-prefixes
Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.
See 10.2.8 fn:namespace-uri-for-prefix
New in 4.0
See 13.1.9 fn:replicate
New in 4.0
See 13.1.12 fn:slice
New in 4.0. The function is identical to the internal op:same-key function in 3.1
See 13.2.1 fn:atomic-equal
PR 1120 1150
A callback function can be supplied for comparing individual items.
See 13.2.2 fn:deep-equal
Changed in 4.0 to use transitive equality comparisons for numeric values.
See 13.2.4 fn:distinct-values
New in 4.0. Originally proposed under the name fn:uniform
See 13.4.6 fn:all-equal
New in 4.0. Originally proposed under the name fn:unique
See 13.4.7 fn:all-different
PR 1117 1279
The $options parameter has been added.
See 13.6.6 fn:unparsed-text-lines
A new function is available for processing input data in HTML format.
See 14.2 Functions on HTML Data
PR 259 956
New in 4.0
See 14.2.3 fn:parse-html
PR 975 1058 1246
An option is provided to control how JSON numbers should be formatted.
See 14.3.4 fn:parse-json
Additional options are available, as defined by fn:parse-json.
See 14.3.5 fn:json-doc
PR 533 719 834 1066
New in 4.0
See 14.4.4 fn:csv-to-arrays
See 14.4.7 fn:parse-csv
PR 533 719 834 1066 1605
New in 4.0
See 14.4.9 fn:csv-to-xml
PR 791 1256 1282 1405
New in 4.0
See 14.5.1 fn:invisible-xml
New in 4.0
See 16.2.4 fn:every
New in 4.0
See 16.2.10 fn:highest
New in 4.0
See 16.2.11 fn:index-where
New in 4.0
See 16.2.12 fn:lowest
New in 4.0
See 16.2.15 fn:scan-right
New in 4.0
See 16.2.16 fn:some
PR 521 761
New in 4.0
See 16.2.21 fn:transitive-closure
New in 4.0
See 17.4.6 map:filter
A third argument is added, allowing user control of how absent keys should be handled.
See 17.4.9 map:get
New in 4.0
See 17.4.10 map:items
PR 478 515
New in 4.0
See 17.4.12 map:keys-where
New in 4.0
See 17.4.14 map:of-pairs
New in 4.0
See 17.4.15 map:pair
New in 4.0
See 17.4.16 map:pairs
New in 4.0
See 17.4.19 map:replace
New in 4.0
See 17.4.19 map:replace
New in 4.0.
See 17.5.7 fn:elements-to-maps
New in 4.0
See 18.2.3 array:empty
A third argument is added, allowing user control of how index-out-of-bounds conditions should be handled.
See 18.2.11 array:get
PR 968 1295
New in 4.0
See 18.2.13 array:index-of
PR 476 1087
New in 4.0
See 18.2.16 array:items
PR 360 476
New in 4.0
See 18.2.18 array:members
See 18.2.19 array:of-members
New in 4.0
See 18.2.22 array:replace18.2.24 array:slice
New in 4.0
See 18.2.25 array:slice
New in 4.0
See 18.2.25 array:slice
New in 4.0
See 18.2.26 array:sort18.2.25 array:sort18.2.2618.2.25 array:sort
New in 4.0
See 18.2.27 array:split18.2.26 array:split18.2.2718.2.26 array:split
Supplying an empty sequence as the value of an optional argument is equivalent to omitting the argument.
See 18.2.28 array:subarray18.2.27 array:subarray18.2.2818.2.27 array:subarray
New functions are provided to obtain information about built-in types and types defined in an imported schema.
See 19 Functions on types
Options are added to customize the form of the output.
See 2.2.6 fn:path
PR 533 719 834
New functions are available for processing input data in CSV (comma separated values) format.
See 14.4 Functions on CSV Data
PR 734 1233
New in 4.0
See 16.2.2 fn:chain
A new function fn:elements-to-maps is provided for converting XDM trees to maps suitable for serialization as JSON. Unlike the fn:xml-to-json function retained from 3.1, this can handle arbitrary XML as input.
See 17.5 Converting Elements to Maps
New in 4.0
See 13.1.5 fn:identity
New in 4.0.
See 4.4.6 fn:divide-decimals
The default for the escape option has been changed to false. The 3.1 specification gave the default value as true, but this appears to have been an error, since it was inconsistent with examples given in the specification and with tests in the test suite.
See 14.3.4 fn:parse-json
The spec has been corrected to note that the function depends on the implicit timezone.
See 13.2.3 fn:compare
In 3.1, given a mixed input sequence such as (1, 3, 4.2e0), the specification was unclear whether it was permitted to add the first two integer items using integer arithmetic, rather than converting all items to doubles before performing any arithmetic. The 4.0 specification is clear that this is permitted; but since the items can be reordered before being added, this is not required.
See 13.4.2 fn:avg
See 13.4.5 fn:sum
It is explicitly stated that the limits for $precision are implementation-defined.
See 4.4.4 fn:round
See 4.4.5 fn:round-half-to-even
For consistency with the new functions map:build and map:of-pairs, the handling of duplicates may now be controlled by the combine option as an alternative to the existing duplicates option.
See 17.4.13 map:merge
PR 173
New in 4.0
See 16.3.4 fn:op
PR 203
New in 4.0
See 17.4.1 map:build
PR 207
New in 4.0
See 10.1.2 fn:parse-QName
See 10.2.5 fn:expanded-QName
PR 222
New in 4.0
See 13.2.7 fn:starts-with-subsequence
See 13.2.8 fn:ends-with-subsequence
See 13.2.9 fn:contains-subsequence
PR 250
New in 4.0
See 13.1.3 fn:foot
See 13.1.15 fn:trunk
See 18.2.2 array:build
See 18.2.8 array:foot
See 18.2.30 array:trunk18.2.29 array:trunk18.2.3018.2.29 array:trunk
PR 258
New in 4.0
See 18.2.14 array:index-where
PR 313
The second argument can now be a sequence of integers.
See 13.1.8 fn:remove
PR 314
New in 4.0
See 17.4.4 map:entries
PR 326
Higher-order functions are no longer an optional feature.
See 1.2 Conformance
PR 419
New in 4.0
See 13.1.7 fn:items-at
PR 434
New in 4.0
See 4.5.2 fn:parse-integer
The function has been extended to allow output in a radix other than 10, for example in hexadecimal.
See 4.6.1 fn:format-integer
PR 482
Deleted an inaccurate statement concerning the behavior of NaN.
See 4.3 Comparison operators on numeric values
PR 507
New in 4.0
See 16.2.13 fn:partition
PR 546
The rules regarding use of non-XML characters in JSON texts have been relaxed.
See 14.3.3 JSON character repertoire
See 14.3.4 fn:parse-json
PR 614
New in 4.0
See 13.2.5 fn:duplicate-values
PR 623
Substantially revised to allow multiple sort key definitions.
See 16.2.17 fn:sort
PR 631
New in 4.0
See 6.3 fn:decode-from-uri
PR 662
Constructor functions now have a zero-arity form; the first argument defaults to the context item.
See 20 Constructor functions
PR 680
The case-insensitive collation is now defined normatively within this specification, rather than by reference to the HTML "living specification", which is subject to change. The collation can now be used for ordering comparisons as well as equality comparisons.
See 5.3.5 The HTML ASCII Case-Insensitive Collation
PR 702
The function can now take any number of arguments (previously it had to be two or more), and the arguments can be sequences of strings rather than single strings.
See 5.4.4 fn:concat
PR 710
Changes the function to return a sequence of key-value pairs rather than a map.
See 16.1.4 fn:function-annotations
PR 727
It has been clarified that loading a module has no effect on the static or dynamic context of the caller.
See 16.3.2 fn:load-xquery-module
PR 795
New in 4.0
See 16.2.18 fn:sort-with
PR 828
The $predicate callback function accepts an optional position argument.
See 16.2.5 fn:filter
See 16.2.6 fn:fold-left
The $action callback function accepts an optional position argument.
See 16.2.7 fn:fold-right
See 16.2.8 fn:for-each
See 16.2.9 fn:for-each-pair
The $predicate callback function now accepts an optional position argument.
See 18.2.4 array:filter
The $action callback function now accepts an optional position argument.
See 18.2.6 array:fold-left
See 18.2.7 array:fold-right
See 18.2.9 array:for-each
See 18.2.10 array:for-each-pair
PR 881
The way that fn:min and fn:max compare numeric values of different types has changed. The most noticeable effect is that when these functions are applied to a sequence of xs:integer or xs:decimal values, the result is an xs:integer or xs:decimal, rather than the result of converting this to an xs:double
See 13.4.3 fn:max
See 13.4.4 fn:min
PR 901
All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.
See 3.1.1 fn:error
The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.
See 3.2.1 fn:trace
The third argument can now be supplied as an empty sequence.
See 5.4.6 fn:substring
The second argument can now be an empty sequence.
See 5.6.5 fn:tokenize
The optional second argument can now be supplied as an empty sequence.
See 6.1 fn:resolve-uri
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
See 9.8.1 fn:format-dateTime
See 9.8.2 fn:format-date
See 9.8.3 fn:format-time
The optional third argument can now be supplied as an empty sequence.
See 13.1.13 fn:subsequence
PR 905
The rule that multiple calls on fn:doc supplying the same absolute URI must return the same document node has been clarified; in particular the rule does not apply if the dynamic context for the two calls requires different processing of the documents (such as schema validation or whitespace stripping).
See 13.6.1 fn:doc
PR 909
The function has been expanded in scope to handle comparison of values other than strings.
See 13.2.3 fn:compare
PR 924
Rules have been added clarifying that users should not be allowed to change the schema for the fn namespace.
See C Schemas
PR 925
The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.
See 4.7.2 fn:format-number
PR 932
The specification now prescribes a minimum precision and range for durations.
See 8.1.2 Limits and precision
PR 933
When comments and processing instructions are ignored, any text nodes either side of the comment or processing instruction are now merged prior to comparison.
See 13.2.2 fn:deep-equal
PR 940
New in 4.0
See 16.2.19 fn:subsequence-where
PR 953
Constructor functions for named record types have been introduced.
See 20.6 Constructor functions for named record types
PR 962
New in 4.0
See 16.2.3 fn:do-until
See 16.2.22 fn:while-do
PR 969
New in 4.0
See 17.4.3 map:empty
PR 984
New in 4.0
See 8.4.1 fn:seconds
PR 987
The order of results is now prescribed; it was previously implementation-dependent.
See 13.2.4 fn:distinct-values
See 13.2.5 fn:duplicate-values
PR 988
New in 4.0
See 14.3.8 fn:pin
See 14.3.9 fn:label
PR 1022
Regular expressions can include comments (starting and ending with #) if the c flag is set.
See 5.6.1 Regular expression syntax
See 5.6.2 Flags
PR 1028
An option is provided to control how the JSON null value should be handled.
See 14.3.4 fn:parse-json
PR 1032
New in 4.0
See 13.1.17 fn:void
PR 1046
New in 4.0
See 16.2.20 fn:take-while
PR 1059
Use of an option keyword that is not defined in the specification and is not known to the implementation now results in a dynamic error; previously it was ignored.
See 1.7 Options
PR 1068
New in 4.0
See 5.4.3 fn:graphemes
PR 1072
The return type is now specified more precisely.
See 16.3.2 fn:load-xquery-module
PR 1090
When casting from a string to a duration or time or dateTime, it is now specified that when there are more digits in the fractional seconds than the implementation is able to retain, excess digits are truncated. Rounding upwards (which could affect the number of minutes or hours in the value) is not permitted.
See 21.2 Casting from xs:string and xs:untypedAtomic
PR 1093
New in 4.0
See 5.3.8 fn:collation
PR 1117
The $options parameter has been added.
See 13.6.5 fn:unparsed-text
See 13.6.7 fn:unparsed-text-available
PR 1182
The $predicate callback function may return an empty sequence (meaning false).
See 16.2.3 fn:do-until
See 16.2.4 fn:every
See 16.2.5 fn:filter
See 16.2.6 fn:fold-left
See 16.2.11 fn:index-where
See 16.2.16 fn:some
See 16.2.20 fn:take-while
See 16.2.22 fn:while-do
See 17.4.6 map:filter
See 17.4.12 map:keys-where
See 18.2.4 array:filter
See 18.2.14 array:index-where
PR 1191
New in 4.0
See 2.3.1 fn:distinct-ordered-nodes
The $options parameter has been added, absorbing the $collation parameter.
See 13.2.2 fn:deep-equal
PR 1250
For selected properties including percent and exponent-separator, it is now possible to specify a single-character marker to be used in the picture string, together with a multi-character rendition to be used in the formatted output.
See 4.7.2 fn:format-number
PR 1257
The $options parameter has been added.
See 14.1.1 fn:parse-xml
See 14.1.2 fn:parse-xml-fragment
PR 1262
New in 4.0
See 5.3.9 fn:collation-available
PR 1265
The constraints on the result of the function have been relaxed.
See 2.1.6 fn:document-uri
PR 1280
As a result of changes to the coercion rules, the number of supplied arguments can be greater than the number required: extra arguments are ignored.
See 16.2.1 fn:apply
PR 1288
Additional error conditions have been defined.
See 14.1.1 fn:parse-xml
PR 1296
New in 4.0
See 16.2.14 fn:scan-left
PR 1333
A new option is provided to allow the content of the loaded module to be supplied as a string.
See 16.3.2 fn:load-xquery-module
PR 1353
An option has been added to suppress the escaping of the solidus (forwards slash) character.
See 14.3.7 fn:xml-to-json
PR 1358
New in 4.0
See 9.3.2 fn:unix-dateTime
PR 1361
The term atomic value has been replaced by atomic item.
See 1.9 Terminology
PR 1393
Changes the function to return a sequence of key-value pairs rather than a map.
See 16.1.4 fn:function-annotations
PR 1409
This section now uses the term primitive type strictly to refer to the 20 atomic types that are not derived by restriction from another atomic type: that is, the 19 primitive atomic types defined in XSD, plus xs:untypedAtomic. The three types xs:integer, xs:dayTimeDuration, and xs:yearMonthDuration, which have custom casting rules but are not strictly-speaking primitive, are now handled in other subsections.
See 21.1 Casting from primitive types to primitive types
The rules for conversion of dates and times to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since these deliver exactly the same result as the XPath 3.1 rules.
See 21.1.2.2 Casting date/time values to xs:string
The rules for conversion of durations to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since the XSD 1.1 rules deliver exactly the same result as the XPath 3.1 rules.
See 21.1.2.3 Casting xs:duration values to xs:string
PR 1455
Numbers now retain their original lexical form, except for any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).
See 14.3.7 fn:xml-to-json
PR 1481
The function has been extended to handle other Gregorian types such as xs:gYearMonth.
See 9.5.1 fn:year-from-dateTime
See 9.5.2 fn:month-from-dateTime
The function has been extended to handle other Gregorian types such as xs:gMonthDay.
See 9.5.3 fn:day-from-dateTime
The function has been extended to handle other types including xs:time.
See 9.5.4 fn:hours-from-dateTime
See 9.5.5 fn:minutes-from-dateTime
The function has been extended to handle other types such as xs:gYearMonth.
See 9.5.7 fn:timezone-from-dateTime
PR 1504
New in 4.0
See 13.1.11 fn:sequence-join
Optional $separator added.
See 18.2.17 array:join
PR 1523
New in 4.0
See 19.1.2 fn:schema-type
See 19.1.4 fn:atomic-type-annotation
See 19.1.5 fn:node-type-annotation
PR 1545
New in 4.0
See 9.6.4 fn:civil-timezone
PR 1570
New in 4.0
See 19.1.3 fn:type-of
PR 1703
The order of entries in maps is retained.
See 14.3.4 fn:parse-json
Ordered maps are introduced.
See 17.1 Ordering of Maps
Enhanced to allow for ordered maps.
See 17.4.6 map:filter
See 17.4.7 map:find
See 17.4.8 map:for-each
See 17.4.17 map:put
See 17.4.18 map:remove

XPath and XQuery Functions and Operators 4.0

W3C Editor's Draft 23 February 2026

Abstract

Status of this Document

Dedication

17 Maps

17.4 Functions that Operate on Maps

17.4.19 map:replace

17.4.2017.4.19 map:size

18 Arrays

18.2 Functions that Operate on Arrays

18.2.22 array:replace

18.2.2318.2.22 array:reverse

18.2.2418.2.23 array:size

18.2.2518.2.24 array:slice

18.2.2618.2.25 array:sort

18.2.2718.2.26 array:split

18.2.2818.2.27 array:subarray

18.2.2918.2.28 array:tail

18.2.3018.2.29 array:trunk

G Changes since version 3.1 (Non-Normative)

G.1 Summary of Changes