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
Available in XPath 3.1, XSLT 3.0, and XQuery 3.1. From Saxon 9.7, available in all editions.
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
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.