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.
It is often useful to decompose a map into a sequence of entries, or key-value pairs (in which the key is an atomic item and the value is an arbitrary sequence). Subsequently it may be necessary to reconstruct a map from these components, typically after modification.
There are two conventional ways of representing a map as a sequence of key-value pairs, each with its own advantages and disadvantages. These are described below:
A map can be represented as a sequence of single-entry maps.
[Definition] A single-entry map is a map containing a single entry.
It is possible to decompose any map into a sequence of single-entry maps, and to construct a map from a sequence of single-entry maps.
For example the map { "x": 1, "y": 2 } can be decomposed to the sequence ({ "x": 1 }, { "y": 2 }).
A map can be represented as a sequence of JNodes.
A JNode holds the map key in its ·selector· property and the corresponding value in its ·content· property.
The following table summarizes the way in which these two representations can be used to compose and decompose maps:
| Operation | Single-Entry Maps | JNodes |
|---|
Decompose a map | map:entries($map)
| $map/child::*
|
Compose a map | map:merge($entries)
| map:build($jnodes, jnode-selector#1, jnode-content#1)
|
Create a single entry | map:entry($key, $value)
| {$key : $value}/child::*
|
Extract the key part of a single entry | map:keys($entry)
| jnode-selector($jnode)
|
Extract the value part of a single entry | map:items($entry)
| jnode-content($jnode)
|
It is also possible to decompose a map using:
The examples below show several ways of constructing a map with the same entries as an input map, but with the entries sorted by key.
Using map:entries and map:merge:
map:entries($map) => sort-by(map:keys#1) => map:merge()
map:entries($map) => sort-by({'key': map:keys#1}) => map:merge()Using JNodes:
$map/* => sort-by(jnode-selector#1) => map:build(jnode-selector#1, jnode-content#1)
$map/* => sort-by({'key': jnode-selector#1}) => map:build(jnode-selector#1, jnode-content#1)Using map:for-each:
map:merge( map:for-each($map, map:entry#2) => sort-by(map:keys#1) )
map:merge( map:for-each($map, map:entry#2) => sort-by({'key': map:keys#1}) )Using an XQuery FLWOR expression:
map:merge( for key $k value $v order by $k return {$k : $v} )