XPath and XQuery Functions and Operators 4.0

18.4.1 map:build

Summary

Returns a map that typically contains one entry for each item in a supplied input sequence.

Signature

map:build(
$input	as item()*,
$keys	as (fn($item as item(), $position as xs:integer) as xs:anyAtomicType*)?	:= fn:identity#1,
$value	as (fn($item as item(), $position as xs:integer) as item()*)?	:= fn:identity#1,
$options	as map(*)	:= {}
) as map(*)

Properties

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

Rules

Informally, the function processes each item in $input in order. It calls the $keys function on that item to obtain a sequence of key values, and the $value function to obtain an associated value. Then, for each key value:

• If the key is not already present in the target map, the processor adds a new key-value pair to the map, with that key and that value.

• If the key is already present, the processor combines the new value for the key with the existing value as determined by the and duplicates option.If the key is already present, the processor combines the new value for the key with the existing value; the way they are combined is determined by the duplicates option.If the key is already present, the processor combines the new value for the key with the existing value as; the way they are combined is determined by the and duplicates option.

  By default, when two duplicate entries occur:

  • A single combined entry will be present in the result.

  • This entry will contain the sequence concatenation^XP of the supplied values.

  • The position of the combined entry in the entry order^DM of the result map will correspond to the position of the first of the duplicates.

  • The key of the combined entry will correspond to the key of one of the duplicates: it is implementation-dependent which one is chosen. (It is possible for two keys to be considered duplicates even if they differ: for example, they may have different type annotations, or they may be xs:dateTime values in different timezones.)

  The $options argument can be used to control the way in which duplicate keys are handled. The allowed options, and their meanings, are the same as for the map:of-pairs function. The option parameter conventions apply.

Formal Equivalent

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

for-each(
  $input, 
  fn($item, $pos) {
    for-each($keys($item, $pos), fn($k) {
      map:pair($k, $value($item, $pos))
    }
  )}
)
=> map:of-pairs($options)

Error Conditions

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.

Notes

The default function for both $keys and $value is the identity function. Although it is permitted to default both, this serves little purpose: usually at least one of these arguments will be supplied.

Examples

Expression:	map:build((), string#1)
Result:	{}
Expression:	map:build(1 to 10, fn { . mod 3 })
Result:	{ 0: (3, 6, 9), 1: (1, 4, 7, 10), 2: (2, 5, 8) } (Returns a map with one entry for each distinct value of . mod 3. The function to compute the value is the identity function, and duplicates are combined by sequence concatenation.)
Expression:	map:build( 1 to 5, value := format-integer(?, "w") )
Result:	{ 1: "one", 2: "two", 3: "three", 4: "four", 5: "five" } (Returns a map with five entries. The function to compute the key is an identity function, the function to compute the value invokes fn:format-integer.)
Expression:	map:build( ("January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"), substring(?, 1, 1) )
Result:	{ "A": ("April", "August"), "D": ("December"), "F": ("February"), "J": ("January", "June", "July"), "M": ("March", "May"), "N": ("November"), "O": ("October"), "S": ("September") }
Expression:	map:build( ("apple", "apricot", "banana", "blueberry", "cherry"), substring(?, 1, 1), string-length#1, { "duplicates": op("+") } )
Result:	{ "a": 12, "b": 15, "c": 6 } (Constructs a map where the key is the first character of an input item, and where the corresponding value is the total string-length of the items starting with that character.)
Expression:	map:build( ('Wang', 'Liu', 'Zhao'), keys := fn($name, $pos) { $name }, value := fn($name, $pos) { $pos } )
Result:	{ "Wang": 1, "Liu": 2, "Zhao": 3 } (Returns an inverted index for the input sequence with the string stored as key and the position stored as value.)
Expression:	let $titles := <titles> <title>A Beginner’s Guide to <ix>Java</ix></title> <title>Learning <ix>XML</ix></title> <title>Using <ix>XML</ix> with <ix>Java</ix></title> </titles> return map:build($titles/title, fn($title) { $title/ix })
Result:	{ "Java": ( <title>A Beginner’s Guide to <ix>Java</ix></title>, <title>Using <ix>XML</ix> with <ix>Java</ix></title> ), "XML": ( <title>Learning <ix>XML</ix></title>, <title>Using <ix>XML</ix> with <ix>Java</ix></title> ) }
The following expression creates a map whose keys are employee @ssn values, and whose corresponding values are the employee nodes:
map:build(//employee, fn { @ssn })
The following expression creates a map whose keys are employee @location values, and whose corresponding values represent the number of employees at each distinct location. Any employees that lack an @location attribute will be excluded from the result.
map:build(//employee, fn { @location }, fn { 1 }, { "duplicates": op("+") })
The following expression creates a map whose keys are employee @location values, and whose corresponding values contain the employee node for the highest-paid employee at each distinct location:
map:build( //employee, keys := fn { @location }, combine := fn($a, $b) { highest(($a, $b), fn { xs:decimal(@salary) }) } )
The following expression creates a map allowing efficient access to every element in a document by means of its fn:generate-id value:
map:build(//*, generate-id#1)