Creates a map that adds a single entry to an existing map, or replaces a single entry (with the specified key) in an existing map.

put($map as map(*), $key as xs:anyAtomicType, $value as item()*) ➔ item()*





The input map




The key to be added or replaced




The new associated value for the specified key




Links to W3C specifications

XPath 3.1 Functions and Operators

XSLT 3.0 Specification

Notes on the Saxon implementation

Available as defined in XSLT 3.0 since Saxon 9.6; in XSLT, XPath, and XQuery, whether or not 3.0 is available.

XPath 3.1 version implemented since Saxon 9.7.

The function is defined to return a new map, leaving the existing map unchanged. Saxon meets this requirement without the overhead of creating a complete copy of the map every time an entry is added. This is achieved using an internal data structure called a trie; this is a tree-like data structure, and when a new entry is added, some new nodes (including a new root) are added to this tree, but most of the existing nodes and their subtrees can be reused without change. In effect the cost of adding an entry is constant, independent of the size of the map.

Performance may suffer if there is a need to check the types of all the keys and values against a required type (e.g. an as="map(xs:integer, xs:string)" attribute on xsl:variable. Saxon uses various techniques to avoid inspecting every entry in the map when this happens, but it cannot always be avoided.