map:put

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()*

Arguments

 

$map

map(*)

The input map

 

$key

xs:anyAtomicType

The key to be added or replaced

 

$value

item()*

The new associated value for the specified key

Result

item()*

Namespace

http://www.w3.org/2005/xpath-functions/map

Links to W3C specifications

XPath 3.1 Functions and Operators

XSLT 3.0 Specification

Saxon availability

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 (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.