Status of this Document
This version of the specification is work in progress. It is produced by the QT4 Working Group, officially the W3C XSLT 4.0 Extensions Community Group. Individual functions specified in the document may be at different stages of review, reflected in their History notes. Comments are invited, in the form of GitHub issues at https://github.com/qt4cg/qtspecs.
Dedication
The publications of this community group are dedicated to our co-chair, Michael Sperberg-McQueen (1954–2024).
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.
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.
Note that when the required type of an argument to a function such as map:build is a map type, then the coercion rules ensure that a JNode can be supplied in the function call: if the ·content· property of the JNode is a map, then the map is automatically extracted as if by the jnode-content function.
| 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 concatenationXP 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:size | Returns the number of entries in the supplied map. |
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.
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:
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: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. |
Changes in 4.0 ⬇ ⬆
Introduced the concept of JNodes. [Issue 2025 PR 2031 11 June 2025]
A JNodeDM is a wrapper around a map or array, or around a value that appears within the content of a map or array. JNodes are described at Section 8.4 JNodesDM. Wrapping a map or array in a JNode enables the use of path expressions such as $jnode/descendant::title, as described at Section 4.6 Path ExpressionsXP.
In addition to the functions defined in this section, functions that operate on JNodes include:
fn:distinct-ordered-nodes
fn:generate-id
fn:root
fn:siblings
fn:transitive-closure
- Summary
Returns the ·content· property of a JNode.
- Signature
fn:jnode-content( |
$input | as jnode-type() | |
) as item()* |
- Properties
This function is deterministic, context-independent, and focus-independent.
- Rules
If $input is an empty sequence, the function returns an empty sequence.
Otherwise, the function returns the ·content· property of $input.
- Notes
In many cases it is unnecessary to make an explicit call on jnode-content, because the coercion rules will take care of this automatically. For example, in an expression such as $X / descendant::name [matches(., '^J')], the call on matches is supplied with a JNode as its first argument; atomization ensures that the actual value being passed to the first argument of matches is the atomized value of the ·content· property.
One case where the function call may be needed is when computing the effective boolean value. As with XNodes, writing if ($array/child::*[1]) ... tests for the existence of a child, it does not test its value. To test its value, write if (jnode-content($array/child::*[1])) ..., or equivalently if (xs:boolean($array/child::*[1])) ....
Other examples where the ·content· of a JNode is extracted automatically include:
Any context where the required type is an atomic value, for example arithmetic operations, value comparisons and general comparisons, and calls on functions that expect an atomic value.
Any context where the required type is a map or array, for example the first argument of functions such as map:size or array:size, a free-standing expression within a map constructor such as map{ $jnode }, the constructs for member and for key/value, the left-hand operand of the lookup operator ? (or the context value in the case of a unary lookup operator), and the operand of a map/array filter expression $jnode?[predicate].
Notable places where the ·content· is not automatically extracted include:
When computing the effective boolean value. As with XNodes, writing if ($array/child::*[1]) ... tests for the existence of a child, it does not test its value. To test its value, write if (jnode-content($array/child::*[1])) ..., or equivalently if (xs:boolean($array/child::*[1])) ....
When calling functions that accept arbitrary sequences, such as count or deep-equal.
It is possible (though probably unwise) to construct a JNode whose ·content· property itself contains another JNode. For example, the expression jnode([jnode([]), jnode([])]) creates a JNode whose ·content· is an array of JNodes, and applying the child axis to this JNode will return a sequence of two JNodes that themselves have further JNodes as their content. The jnode-content returns these contained JNodes, it does not recursively extract their content.
- Examples
| Expression: | let $array := [1, 3, 4.5, 7, "eight", 10]
return $array / child::type(xs:integer) =!> jnode-content() |
|---|
| Result: | |
|---|
| Expression: | let $map := {'Mo': 'Monday', 'Tu': 'Tuesday', 'We': 'Wednesday'}
return $map / child::get("Mo", "We", "Fr", "Su") =!> jnode-content() |
|---|
| Result: | |
|---|
| Expression: | let $array := [[4, 18], [30, 4, 22]]
return $array / descendant::*[. gt 25][1] / ancestor-or-self::* =!> jnode-content() => reverse() |
|---|
| Result: | [[4, 18], [30, 4, 22]], [30, 4, 22], 30 |
|---|