map:merge

Creates a new map that combines entries from a number of existing maps. There is one entry in the new map for each distinct key present in the union of the input maps; the way duplicate keys are handled is determined by the supplied $options.

WARNING: Since 9.7.0.8, the changes in the W3C Specification introduce a significant change to the default behaviour of the function when there are duplicate keys. Previously (up to and including 9.7.0.7), the associated value for each key in the new map was taken from the last map in the input sequence containing that key. From 9.7.0.8, the default behaviour is to take the value from the first map containing that key.

merge($maps as map(*)*) ➔ map(*)

Arguments
	$maps	map()	The input maps
Result		map(*)

merge($maps as map(*)*, $options as map(*)) ➔ map(*)

Arguments
	$maps	map()	The input maps
	$options	map(*)	Used to control the way in which merging takes place
Result		map(*)

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

In Saxon 10, several vendor-defined options are recognized. These are QName-valued keys in the Saxon namespace:

saxon:on-duplicates as function($a, $b). The value of the option is a user-defined function which is called when a duplicate key is encountered. The two arguments are the existing value associated with the key, and the new value to be associated with the key. The result of the function is the value that will be stored in the result map. For example map:merge(({"a":12}, {"a":17}), map{QName("http://saxon.sf.net/", "on-duplicates"): function($a, $b){$a + $b}})?a returns 29: the value stored in the result map is the sum of all the values associated with the key. Other possibilities that might be useful are to return the string-join, the average, or the min or max, or to throw an error conditionally only if the two values are different. Specifying function($a, $b){$a} emulates the standard option duplicates:use-first, while function($a, $b){$b} emulates duplicates:use-last, and function($a, $b){$a, $b} emulates duplicates:combine.
saxon:duplicates-error-code: defines an error code to be used when the duplicates:reject option is in force (this is provided primarily for Saxon internal use, since map:merge is used to underpin other functionality such as the XSLT xsl:map instruction).
saxon:key-type. The value should be the local name of a primitive type to which all the keys are expected to conform. The only value treated specially is "string": when all the key values are expected to be strings, Saxon uses an internal data structure optimized for this purpose. This is purely an optimization hint; no error occurs if a non-string value is encountered (but the map then has to be reorganized internally, which is costly).
saxon:final. The value is a boolean; the value true is an optimization hint that indicates that the application does not intend to make any further changes to the constructed map. This enables Saxon to use an internal data structure that does not allow such modifications. This is purely an optimization hint; no error occurs if subsequent put or remove operations are performed (but the map then has to be reorganized internally, which is costly).

For a history of changes in previous Saxon releases, see the Saxon 9.9 documentation.