saxon:key-map

To use this function, it is first necessary to declare a key as a range key, which can be done using a declaration such as:

<xsl:key name="k" match="transaction" use="@date" saxon:range-key="yes"/>

The effect of this declaration is that Saxon builds the index underpinning the key using a Java TreeMap rather than a HashMap, making ordered traversal possible. At present a key can be declared as a range key only if the keys are of type string (or untypedAtomic), and if the Unicode codepoint collation is used. If there are several xsl:key elements with the same name, declaring any one of them as a range key is sufficient.

The effect of the saxon:key-map() function is to construct a map (actually, a wrapper for the underlying index), in which the entries represent the nodes selected by the match pattern of the xsl:key declaration within the document identified by the doc argument. The min and max arguments restrict the map to those entries whose keys lie between the min and max values respectively; either argument can be set to an empty sequence to indicate an open-ended range of key values.

In the resulting map, the function map:keys() is guaranteed to return keys in sorted order. (This does not apply, however, if new maps are constructed from this map by adding or removing entries or combining several maps).

The resulting map can be used using all the functions available for maps, for example map:get() to get an entry, map:keys() to enumerate the key values, map:is-empty() to determine if the map is empty, and so on. The maps for several documents can be combined into a single map using a construct such as:

map:new(collection('dir?select="*.xml')!saxon:key-map('k', ., (), ()))

Note however that the resulting map will not be sorted.