saxon:key-map

Returns a map providing access to the index constructed using xsl:key.

key-map($key as xs:string, $doc as document-node(), $min as xs:string?, $max as xs:string?) ➔ map(xs:string, node()*)

Arguments

 

$key

xs:string

The name of the key

 

$doc

document-node()

The root of the tree

 

$min

xs:string?

The low end of the required key range

 

$max

xs:string?

The high end of the required key range

Result

map(xs:string, node()*)

Namespace

http://saxon.sf.net/

Saxon availability

Requires Saxon-PE or Saxon-EE. Implemented since Saxon 9.5. Available for Java and C/C++ only (not .NET).

Notes on the Saxon implementation

Available since Saxon 9.5. Applicable to XSLT only. Not available in SaxonCS.

Details

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:merge(collection('dir?select="*.xml')!saxon:key-map('k', ., (), ()))

Note however that the resulting map will not be sorted.