The Map Extension

This is a family of extension functions, map:new(), map:put(), map:get(), and map:keys() that can be used to maintain a general purpose map from atomic values to arbitrary XDM sequences. The functions are in namespace http://ns.saxonica.com/map, and are available in Saxon-PE and Saxon-EE only.

The map itself is an object of type javatype:com.saxonica.functions.map.ImmutableMap, where the prefix javatype corresponds to the namespace URI http://saxon.sf.net/java-type.

The map is immutable: adding an entry to a map creates a new map, leaving the original map unchanged. These are therefore pure functions. Under the hood, the implementation avoids copying data whereever possible to minimise the use of memory when a map is built incrementally.

The individual methods are described below:

Creating a new map

map:new() ==> javatype:com.saxonica.functions.map.ImmutableMap

This method creates a new empty map

Adding a value to the map

map:put(javatype:com.saxonica.functions.map.ImmutableMap, xs:anyAtomicType key, item()* value) ==> javatype:com.saxonica.functions.map.ImmutableMap

This method creates and returns a new map that differs from the supplied map by adding or replacing a single entry. The key for the new entry is an atomic value supplied as $key, the value is supplied as $value. The new entry is added to the map, replacing any existing entry for the same key. Adding an entry whose value is the empty sequence is equivalent to removing the entry from the map.

Getting a value from the map

map:get(javatype:javatype:com.saxonica.functions.map.ImmutableMap, xs:anyAtomicType key) ==> item()*

This method locates the entry in the map for the given key, if there is one, and returns it. If there is no entry, it returns the empty sequence. Keys are compared using the XPath eq operator, except that no error occurs in the case of incomparable types; the collation used is the Unicode codepoint collation.

Example

This example creates a map reflecting the contents of an input file, and then uses it to perform a look-up.