XPath and XQuery Functions and Operators 4.0

Returns a map that combines the entries from a number of existing maps.

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

The function map:mergereturns a map that is formed by combining the contents of the maps supplied in the $maps argument.

Informally, the supplied maps are combined as follows:

1. There is one entry in the returned map for each distinct key present in the union of the input maps, where two keys are distinct if they are not the ·same key·.

2. If there are duplicate keys, that is, if two or more maps contain entries having the ·same key·, then the way this is handled is controlled by the second ($options) argument.

The definitive specification is as follows.

1. If the second argument is omitted or an empty sequence, the effect is the same as calling the two-argument function with an empty map as the value of $options.

2. The $options argument can be used to control the way in which duplicate keys are handled. The ·option parameter conventions· apply.

3. The entries that may appear in the $options map are as follows:

   record(
   duplicates?	as xs:string
   )

   Key	Value	Meaning
   duplicates?	Determines the policy for handling duplicate keys: specifically, the action to be taken if two maps in the input sequence $maps contain entries with key values K1 and K2 where K1 and K2 are the ·same key·. Type: xs:string Default: use-first
   	reject	An error is raised [err:FOJS0003] if duplicate keys are encountered.
   	use-first	If duplicate keys are present, all but the first of a set of duplicates are ignored, where the ordering is based on the order of maps in the $maps argument.
   	use-last	If duplicate keys are present, all but the last of a set of duplicates are ignored, where the ordering is based on the order of maps in the $maps argument.
   	use-any	If duplicate keys are present, all but one of a set of duplicates are ignored, and it is ·implementation-dependent· which one is retained.
   	combine	If duplicate keys are present, the result map includes an entry for the key whose associated value is the sequence concatenationXP of all the values associated with the key, retaining order based on the order of maps in the $maps argument. The key value in the result map that corresponds to such a set of duplicates must be the ·same key· as each of the duplicates, but it is otherwise unconstrained: for example if the duplicate keys are xs:byte(1) and xs:short(1), the key in the result could legitimately be xs:long(1).

The effect of the function is equivalent to the result of the following XPath expression, except in error cases.

let $FOJS0003 := QName("http://www.w3.org/2005/xqt-errors", "FOJS0003")
let $duplicates-handler := {
  "use-first": fn($a, $b) { $a },
  "use-last":  fn($a, $b) { $b },
  "combine":   fn($a, $b) { $a, $b },
  "reject":    fn($a, $b) { fn:error($FOJS0003) },
  "use-any":   fn($a, $b) { fn:random-number-generator()?permute(($a, $b))[1] }
}
let $combine := fn($A as map(*), $B as map(*), $deduplicator as fn(*)) {
  fold-left(map:keys($B), $A, fn($z, $k) { 
    if (map:contains($z, $k))
    then map:put($z, $k, $deduplicator($z($k), $B($k)))
    else map:put($z, $k, $B($k))
  })
}
return fold-left($maps, dm:empty-map($options?ordering otherwise "undefined"),
  $combine(?, ?, $duplicates-handler($options?duplicates otherwise "use-first"))
)

let $FOJS0003 := QName("http://www.w3.org/2005/xqt-errors", "FOJS0003")
let $duplicates-handler := {
  "use-first": fn($a, $b) { $a },
  "use-last":  fn($a, $b) { $b },
  "combine":   fn($a, $b) { $a, $b },
  "reject":    fn($a, $b) { fn:error($FOJS0003) },
  "use-any":   fn($a, $b) { fn:random-number-generator()?permute(($a, $b))[1] }
}
let $combine := fn($A as map(*), $B as map(*), $deduplicator as fn(*)) {
  fold-left(map:keys($B), $A, fn($z, $k) { 
    if (map:contains($z, $k))
    then map:put($z, $k, $deduplicator($z($k), $B($k)))
    else map:put($z, $k, $B($k))
  })
}
return fold-left($maps, {},
  $combine(?, ?, $duplicates-handler($options?duplicates otherwise "use-first"))
)

An error is raised [err:FOJS0003] if the value of $options indicates that duplicates are to be rejected, and a duplicate key is encountered.

An error is raised [err:FOJS0005] if the value of $options includes an entry whose key is defined in this specification, and whose value is not a permitted value for that key.

If the input is an empty sequence, the result is an empty map.

If the input is a sequence of length one, the result map is indistinguishable from the supplied map.

There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example map(xs:integer, xs:string)) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.

Returns a map that combines data from a sequence of ·key-value pair maps·.

This function is ·deterministic·, ·context-independent·, and ·focus-independent·.

The function map:of-pairsreturns a map that is formed by combining ·key-value pair maps· supplied in the $input argument.

The $options argument can be used to control the ordering of the result, and the way in which duplicate keys are handled. The ·option parameter conventions· apply.

The entries that may appear in the $options map are as follows:

The effect of the function is equivalent to the result of the following XPath expression.

map:build($input, map:get(?, 'key'), map:get(?, 'value'), $combine)

The function can be made to fail with a dynamic error in the event that duplicate keys are present in the input sequence by supplying a $combine function that invokes the fn:error function.

If the input is an empty sequence, the result is an empty map.

There is no requirement that the supplied key-value pairs should have the same or compatible types. The type of a map (for example map(xs:integer, xs:string)) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.