XPath and XQuery Functions and Operators 4.0

17 Maps

Maps were introduced as a new datatype in XDM 3.1. This section describes functions that operate on maps.

A map is a kind of item.

[Definition] A map consists of a sequence of entries, also known as key-value pairs. Each entry comprises a key which is an arbitrary atomic item, and an arbitrary sequence called the associated value.

[Definition] Within a map, no two entries have the same key. Two atomic items K1 and K2 are the same key for this purpose if the function call fn:atomic-equal($K1, $K2) returns true.

It is not necessary that all the keys in a map should be of the same type (for example, they can include a mixture of integers and strings).

Maps are immutable, and have no identity separate from their content. For example, the map:remove function returns a map that differs from the supplied map by the omission (typically) of one entry, but the supplied map is not changed by the operation. Two calls on map:remove with the same arguments return maps that are indistinguishable from each other; there is no way of asking whether these are “the same map”.

A map can also be viewed as a function from keys to associated values. To achieve this, a map is also a function item. The function corresponding to the map has the signature function($key as xs:anyAtomicValue) as item()*. Calling the function has the same effect as calling the map:get function: the expression $map($key) returns the same result as get($map, $key). For example, if $books-by-isbn is a map whose keys are ISBNs and whose assocated values are book elements, then the expression $books-by-isbn("0470192747") returns the book element with the given ISBN. The fact that a map is a function item allows it to be passed as an argument to higher-order functions that expect a function item as one of their arguments.

17.4 Functions that Operate on Maps

The functions defined in this section use a conventional namespace prefix map, which is assumed to be bound to the namespace URI http://www.w3.org/2005/xpath-functions/map.

The function call map:get($map, $key) can be used to retrieve the value associated with a given key.

There is no operation to atomize a map or convert it to a string. The function fn:serialize can in some cases be used to produce a JSON representation of a map.

Function	Meaning
`map:build`	Returns a map that typically contains one entry for each item in a supplied input sequence.
`map:contains`	Tests whether a supplied map contains an entry for a given key.
`map:empty`	Returns `true` if the supplied map contains no entries.
`map:entries`	Returns a sequence containing all the key-value pairs present in a map, each represented as a ·singleton map·.
`map:entry`	Returns a ·singleton map· that represents a single key-value pair.
`map:filter`	Selects entries from a map, returning a new map.
`map:find`	Searches the supplied input sequence and any contained maps and arrays for a map entry with the supplied key, and returns the corresponding values.
`map:for-each`	Applies a supplied function to every entry in a map, returning the sequence concatenation^XP of the results.
`map:get`	Returns the value associated with a supplied key in a given map.
`map:items`	Returns a sequence containing all the values present in a map, in order.
`map:keys`	Returns a sequence containing all the keys present in a map.
`map:keys-where`	Returns a sequence containing selected keys present in a map.
`map:merge`	Returns a map that combines the entries from a number of existing maps.
`map:of-pairs`	Returns a map that combines data from a sequence of ·key-value pair maps·.
`map:pair`	Returns a ·key-value pair map· that represents a single key-value pair.
`map:pairs`	Returns a sequence containing all the key-value pairs present in a map, each represented as a ·key-value pair map·.
`map:put`	Returns a map containing all the contents of the supplied map, but with an additional entry, which replaces any existing entry for the same key.
`map:remove`	Returns a map containing all the entries from a supplied map, except those having a specified key.
`map:replace`	Returns a map based on the contents of an existing map, computing a new value to be associated with a supplied key.
`map:size`	Returns the number of entries in the supplied map.

17.4.1 map:build

Changes in 4.0 ⬇ ⬆

New in 4.0 [Issue 151 PR 203 18 October 2022]

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 calls the combine function in the $options argument to combine the existing value for the key with the new value, and replaces the entry with this combined value.
The key of the combined entry is taken from one of the duplicate entries: it is ·implementation-defined· which one is used. (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 with different timezones.)
The position of the combined entry in the entry order^DM of the result map is based on the position of the first entry having that key in the input sequence (that is, the order of keys in the result is the order of first appearance in the input.

The $options argument can be used to control the 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:

`record(`
`combine?`	`as` `(fn($existing-value as item(), $new-value as item()) as item()*)?`
`)`

Key	Value	Meaning
`combine?`	A function that is used to combine two different values that are supplied for the same key. The default is to combine the two values using sequence concatenation^XP, retaining their order in the input sequence. Type: `(fn($existing-value as item(), $new-value as item()) as item())?` Default:* `fn:op(',')`
`combine?`	`User-supplied function`	The function is called for any entry in an input map that has the ·same key· as a previous entry. The first argument is the existing value associated with the key; the second argument is the value associated with the key in the duplicate input entry, and the result is the new value to be associated with the key.
`User-supplied function`	The function is called for any entry in an input map that has the ·same key· as a previous entry. The first argument is the existing value associated with the key; the second argument is the value associated with the key in the duplicate input entry, and the result is the new value to be associated with the key.

Formal Equivalent

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

fold-left($input, {}, fn($map, $item, $pos) {
  let $v := $value($item, $pos)
  return fold-left($keys($item, $pos), $map, fn($m, $k) {
    if (map:contains($m, $k)) then (
      map:put($m, $k, $combine($m($k), $v))
    ) else (
      map:put($m, $k, $v)
    )
  })
})

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.

The default action for combining entries with duplicate keys is to perform a sequence concatenation^XP of the corresponding values, equivalent to the duplicates: combine option on map:merge. Other potentially useful functions for combining duplicates include:

fn($a, $b) { $a } Use the first value and discard the remainder
fn($a, $b) { $b } Use the last value and discard the remainder
fn:concat(?, ",", ?) Form the string-concatenation of the values, comma-separated
fn:op('+') Compute the sum of the values

The order of entries^DM in the result reflects the order of the items in $input from which they were derived. In the event that two entries have duplicate keys, the position of the combined entry in the result reflects the position of the first input item with that key.

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, { "combine": 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 }, { "combine": 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)

17.4.13 map:merge

Changes in 4.0 ⬇ ⬆

For consistency with the new functions map:build and map:of-pairs, the handling of duplicates may now be controlled by the combine option as an alternative to the existing duplicates option. [Issue 1725 ]

Summary

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

Signature

`map:merge`(
`$maps`	`as` `map()`,
`$options`	`as` `map(*)?`	`:=` `{}`
) `as` `map(*)`

Properties

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

Rules

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:

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

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.
The $options argument can be used to control the way in which duplicate keys are handled. The ·option parameter conventions· apply.
In the event that two or more entries in the input maps have the ·same key·:
1. A single entry is created by combining the values of the duplicates, in a way determined by the supplied $options.
2. The key of the combined entry is one of the duplicate keys: which one is chosen is ·implementation-defined·. (Two keys that are deemed duplicates may differ: for example they may have different type annotations, or they may be xs:dateTime values with different timezones.)
3. The position of the combined entry in the entry order^DM of the result map corresponds to the position of the first appearance of the corresponding key value in the input.
In the event that two or more entries in the input maps have the ·same key·:
1. A single entry is created by combining the values of the duplicates, in a way determined by the supplied $options.
2. The key of the combined entry is one of the duplicate keys: which one is chosen is ·implementation-defined·. (Two keys that are deemed duplicates may differ: for example they may have different type annotations, or they may be xs:dateTime values with different timezones.)
3. The position of the combined entry in the entry order^DM of the result map corresponds to the position of the first appearance of the corresponding key value in the input.

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

`record(`
`duplicates?`	`as` `xs:stringas` `xs:string`,`as` `xs:string`,
`combine?`	`)as` `)(fn($existing-value as item(), $new-value as item()) as item()*)?`
`)`
`)`

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 `K₁` and `K₂` where `K₁` and `K₂` are the ·same key·. This option and the `combine` option are mutually exclusive. Type: `xs:string` Default: `use-first`
	`reject`	AnEquivalent to specifying `error is"combine": fn(){error(xs:QName("err:FOJS0003"), ...)` raised [(the remainingerr:FOJS0003] if duplicate keys arguments to `fn:error` are encounteredbeing ·implementation-defined·).
	`use-first`	If duplicateEquivalent to specifying `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"combine": fn($a, $b){ $mapsa argument}`.
	`use-last`	If duplicateEquivalent to specifying `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"combine": fn($a, $b){ $mapsb argument}`.
	`use-any`	If duplicateEquivalent to specifying `keys are present, all but one of"combine": fn($a, $b){ one-of($a, $b) }` awhere `setone-of` of duplicateschooses either `are$a` ignored,or `and$b` it isin an ·implementation-dependent··implementation-defined··implementation-dependentdefined· which one is retainedway.
	`combine`	Equivalent to specifying `"combine": fn($a, $b){ $a, $b }`.
`combine`	Equivalent to specifying `"combine": fn($a, $b){ $a, $b }`.
`combine?`	Supplies a function for handling duplicate keys: specifically, the action to be taken if two maps in the input sequence `$maps` contain entries with key values `K₁` and `K₂` where `K₁` and `K₂` are the ·same key·. This option and the `duplicates` option are mutually exclusive. Type: `(fn($existing-value as item(), $new-value as item()) as item())?` Default:* `fn($a, $b){ $a }`
`combine?`	`combine?`	Supplies a function for handling duplicate keys: specifically, the action to be taken if two maps in the input sequence `$maps` contain entries with key values `K₁` and `K₂` where `K₁` and `K₂` are the ·same key·. This option and the `duplicates` option are mutually exclusive. Type: `(fn($existing-value as item(), $new-value as item()) as item())?` Default:* `fn($a, $b){ $a }`
`combineUser-supplied functioncombineUser-supplied function`	`combine?`	If duplicate keys areA function with signature `present, the result map includes an entry for the key whose associated value is the fn(item()sequence concatenationXP of all the values associated with the key, retaining order based on the order of maps in the , item()) as item$maps()*` argument. The key value in the result map that corresponds to such a set of duplicates must be. The function is called for any entry in an input map that has the ·same key· as each of the duplicates, but it is otherwise unconstrained: for example if the duplicate keys area previous entry. The first argument is the existing value associated xs:byte(1)with andthe xs:short(1)key;, the second argument is the value associated with the key in the result could legitimatelyduplicate input entry, and the result is the new value to be xs:long(1)associated with the key.

Formal Equivalent

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, {},
  $combine(?, ?, $duplicates-handler($options?duplicates otherwise "use-first"))
)

let $FOJS0003 := QName("http://www.w3.org/2005/xqt-errors", "FOJS0003")
let $combiner := $options?combine
  otherwise {
      "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] }
    } ($options?duplicates)
  otherwise        fn($a, $b) { $a }
  
return map:of-pairs($maps =!> map:pairs(), { "combine": $combiner });

Error Conditions

An error is raised [err:FORG0013] if both the combine and duplicates options are present.

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

Note:

By way of explanation, $combine is a function that combines two maps by iterating over the keys of the second map, adding each key and its corresponding value to the first map as it proceeds. The second call of fn:fold-left in the return clause then iterates over the maps supplied in the call to map:merge, accumulating a single map that absorbs successive maps in the input sequence by calling $combine.

This algorithm processes the supplied maps in a defined order, but processes the keys within each map in implementation-dependent order.

By way of explanation, the function first reduces the sequence of input maps to a sequence of key-value pairs, retaining order of both the maps and of the entries within each map. It then combines key-value pairs having the ·same key· by applying the $combine function successively to pairs of duplicates. The position in the entry order^DM of the result map of an entry formed by combining duplicates corresponds to the position of the first occurrence of the key in the input sequence. This is true even whien the option use-last is used: the value of the resulting entry corresponds to the last entry with a given key, but the position of the entry in the result map corresponds to the position of the first entry with that key.

The use of fn:random-number-generator represents one possible conformant implementation for "duplicates": "use-any", but it is not the only conformant implementation and is not intended to be a realistic implementation. The purpose of this option is to allow the implementation to use whatever strategy is most efficient; for example, if the input maps are processed in parallel, then specifying "duplicates": "use-any" means that the implementation does not need to keep track of the original order of the sequence of input maps.

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.

Examples

Variables
let $week := { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" }

Expression:	`map:merge(())`
Result:	{} (Returns an empty map).
Expression:	map:merge(( map:entry(0, "no"), map:entry(1, "yes") ))
Result:	{ 0: "no", 1: "yes" } (Returns a map with two entries).
Expression:	map:merge( ($week, { 7: "Unbekannt" }) )
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" } (The value of the existing map is unchanged; the returned map contains all the entries from `$week`, supplemented with an additional entry.)
Expression:	map:merge( ($week, { 6: "Sonnabend" }), { "duplicates": "use-last" } )
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" } (The value of the existing map is unchanged; the returned map contains all the entries from `$week`, with one entry replaced by a new entry. Both input maps contain an entry with the key `6`; the one used in the result is the one that comes last in the input sequence.)
Expression:	map:merge( ($week, { 6: "Sonnabend" }), { "duplicates": "use-first" } )
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" } (The value of the existing map is unchanged; the returned map contains all the entries from `$week`, with one entry replaced by a new entry. Both input maps contain an entry with the key `6`; the one used in the result is the one that comes first in the input sequence.)
Expression:	map:merge( ($week, { 6: "Sonnabend" }), { "duplicates": "combine" } )
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: ("Samstag", "Sonnabend") } (The value of the existing map is unchanged; the returned map contains all the entries from `$week`, with one entry replaced by a new entry. Both input maps contain an entry with the key `6`; the entry that appears in the result is the sequence concatenation^XP of the entries in the input maps, retaining order.)
Expression:	map:merge(({ "red": 0 }, { "green": 1}, { "blue": 2 })) => map:keys()
Result:	"red", "green", "blue"

17.4.14 map:of-pairs

Changes in 4.0 ⬇ ⬆

New in 4.0

Summary

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

Signature

`map:of-pairs`(
`$input`	`as` `key-value-pair*`,
`$options`	`as` `map(*)`	`:=` `{}`
) `as` `map(*)`

Properties

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

Rules

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 handling of duplicates is defined to be the same as in an equivalent call of the map:build function: see the formal equivalent below.

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

`record(`
`combine?`	`as` `(fn($existing-value as item(), $new-value as item()) as item()*)?`
`)`

Key	Value	Meaning
`combine?`	A function that is used to combine two different values that are supplied for the same key. The default is to combine the two values using sequence concatenation^XP, retaining their order in the input sequence. Type: `(fn($existing-value as item(), $new-value as item()) as item())?` Default:* `fn:op(',')`
`combine?`	`User-supplied function`	The function is called for any entry in an input map that has the ·same key· as a previous entry. The first argument is the existing value associated with the key; the second argument is the value associated with the key in the duplicate input entry, and the result is the new value to be associated with the key.
`User-supplied function`	The function is called for any entry in an input map that has the ·same key· as a previous entry. The first argument is the existing value associated with the key; the second argument is the value associated with the key in the duplicate input entry, and the result is the new value to be associated with the key.

Formal Equivalent

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)

Error Conditions

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.

Notes

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.

Examples

Variables
let $week := { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" }

Expression:	`map:of-pairs(())`
Result:	{} (Returns an empty map).
Expression:	`map:of-pairs(map:pairs($week))`
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" } (The function `map:of-pairs` is the inverse of `map:pairs`.)
Expression:	map:of-pairs(( { "key": 0, "value": "no" }, { "key": 1, "value": "yes" } ))
Result:	{ 0: "no", 1: "yes" } (Returns a map with two entries).
Expression:	map:of-pairs(( map:pairs($week), { "key": 7, "value": "Unbekannt" } ))
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" } (The value of the existing map is unchanged; the returned map contains all the entries from `$week`, supplemented with an additional entry.)
Expression:	map:of-pairs(( map:pairs($week), { "key": 6, "value": "Sonnabend" } ))
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: ("Samstag", "Sonnabend") } (The value of the existing map is unchanged; the returned map contains all the entries from `$week`, with one entry replaced by a new entry. Both input maps contain an entry with the key `6`; the one used in the result combines the two supplied values into a single sequence.)
Expression:	map:of-pairs( (map:pairs($week), { "key": 6, "value": "Sonnabend" }), fn($old, $new) { $new } )
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" } (The value of the existing map is unchanged; the returned map contains all the entries from `$week`, with one entry replaced by a new entry. Both input maps contain an entry with the key `6`; the supplied `$combine` function ensures that the one used in the result is the one that comes last in the input sequence.)
Expression:	map:of-pairs( (map:pairs($week), { "key": 6, "value": "Sonnabend" }), fn($old, $new) { `{ $old }\|{ $new }` } )
Result:	{ 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag\|Sonnabend" } (In the result map, the value for key `6` is obtained by concatenating the values from the two input maps, with a separator character.)
Expression:	map:of-pairs((map:pair("red": 0), map:pair("green": 1), map:pair("blue": 2 )) => map:keys()
Result:	"red", "green", "blue" (The keys are returned in the order supplied.)
Expression:	{ "red": 0, "green": 1, "blue": 2 } => map:pairs() => sort(keys := fn{ ?key }) => map:of-pairs()) => map:keys()
Result:	"blue", "green", "red" (Takes any map and produces a map with the same entries, but sorted by key.)
Expression:	map:of-pairs((map:pair("red": 0), map:pair("green": 1), map:pair("blue": 2 )) => map:put("yellow": -1) => map:keys()
Result:	"red", "green", "blue", "yellow" (New entries are added at the end.)
The following expression takes an existing map and sorts its entries into key order:
map:of-pairs(map:pairs($M) => sort(keys:=fn{?key}))

B Error summary

The error text provided with these errors is non-normative.

err:FOAP0001, Wrong number of arguments.

Raised when fn:apply is called and the arity of the supplied function is not the same as the number of members in the supplied array.

err:FOAR0001, Division by zero.

This error is raised whenever an attempt is made to divide by zero.

err:FOAR0002, Numeric operation overflow/underflow.

This error is raised whenever numeric operations result in an overflow or underflow.

err:FOAY0001, Array index out of bounds.

This error is raised when an integer used to select a member of an array is outside the range of values for that array.

err:FOAY0002, Negative array length.

This error is raised when the $length argument to array:subarray is negative.

err:FOCA0001, Input value too large for decimal.

Raised when casting to xs:decimal if the supplied value exceeds the implementation-defined limits for the datatype.

err:FOCA0002, Invalid lexical value.

Raised by fn:resolve-QName and fn:QName when a supplied value does not have the lexical form of a QName or URI respectively; and when casting to decimal, if the supplied value is NaN or Infinity.

err:FOCA0003, Input value too large for integer.

Raised when casting to xs:integer if the supplied value exceeds the implementation-defined limits for the datatype.

err:FOCA0005, NaN supplied as float/double value.

Raised when multiplying or dividing a duration by a number, if the number supplied is NaN.

err:FOCA0006, String to be cast to decimal has too many digits of precision.

Raised when casting a string to xs:decimal if the string has more digits of precision than the implementation can represent (the implementation also has the option of rounding).

err:FOCH0001, Codepoint not valid.

Raised by fn:codepoints-to-string if the input contains an integer that is not the codepoint of a ·permitted character·.

err:FOCH0002, Unsupported collation.

Raised by any function that uses a collation if the requested collation is not recognized.

err:FOCH0003, Unsupported normalization form.

Raised by fn:normalize-unicode if the requested normalization form is not supported by the implementation.

err:FOCH0004, Collation does not support collation units.

Raised by functions such as fn:contains if the requested collation does not operate on a character-by-character basis.

err:FOCH0005, Unrecognized or invalid character name.

Raised by fn:char if the supplied character name is not recognized, or if it represents a codepoint that is not a ·permitted character·.

err:FOCV0001, CSV field quoting error.

Raised when parsing CSV input if a syntax error in the input CSV is found.

err:FOCV0002, Invalid CSV delimiter error.

Raised when parsing CSV input if the field-separator, record-separator, or quote-character option is set to an invalid value.

err:FOCV0003, Duplicate CSV delimiter error.

Raised when parsing CSV input if the same delimiter character is assigned to more than one role.

err:FOCV0004, Argument supplied is not a known column name.

Raised by the function from the get entry of csv-columns-record, if its $key argument is an xs:string and is not one of the known column names.

err:FODC0001, No context document.

Raised by fn:id, fn:idref, and fn:element-with-id if the node that identifies the tree to be searched is a node in a tree whose root is not a document node.

err:FODC0002, Error retrieving resource.

Raised by fn:doc, fn:collection, and fn:uri-collection to indicate that either the supplied URI cannot be dereferenced to obtain a resource, or the resource that is returned is not parseable as XML.

err:FODC0003, Function not defined as deterministic.

Raised by fn:doc, fn:collection, and fn:uri-collection to indicate that it is not possible to return a result that is guaranteed deterministic.

err:FODC0004, Invalid collection URI.

Raised by fn:collection and fn:uri-collection if the argument is not a valid xs:anyURI.

err:FODC0005, Invalid URI reference.

Raised (optionally) by fn:doc if the argument is not a valid xs:anyURI.

err:FODC0006, String passed to fn:parse-xml is not a well-formed XML document.

Raised by fn:parse-xml if the supplied string is not a well-formed and namespace-well-formed XML document; or if DTD validation is requested and the document is not valid against its DTD.

err:FODC0007, String passed to fn:parse-xml is not a DTD-valid XML document.

Raised by fn:parse-xml if DTD validation is requested and the supplied string has no DTD or is not valid against the DTD.

err:FODC0008, Invalid value for the xsd-validation option of fn:parse-xml.

Raised when the xsd-validation option to fn:parse-xml is supplied, and the value is not one of the permitted values; for example if the option type Q{U}NNN is used, and Q{U}NNN does not identify a type in the static context.

err:FODC0009, Processor is not schema-aware.

Raised when the xsd-validation option to fn:parse-xml is set to a value other than skip, if the processor is not schema-aware.

err:FODC0010, The processor does not support serialization.

Raised when fn:serialize is called and the processor does not support serialization, in cases where the host language makes serialization an optional feature.

err:FODC0011, String passed to fn:parse-html is not a well-formed HTML document.

Raised by fn:parse-html if the supplied string is not a well-formed HTML document.

err:FODC0012, Unsupported HTML parser option.

Raised by fn:parse-html if a key passed to $options, or its value, is not supported by the implementation.

err:FODC0013, No validating XML parser available.

Raised when the dtd-validation option to fn:parse-xml is set, if no validating XML parser is available. Note: it is recommended that all processors should support the dtd-validation option, but there may be environments (such as web browsers) where this is not practically feasible.

err:FODC0014, String passed to fn:parse-xml is not a schema-valid XML document.

Raised by fn:parse-xml if XSD validation is requested and the XML document represented by the supplied string is not valid against the relevant XSD schema.

err:FODF1280, Invalid decimal format name.

This error is raised if the decimal format name supplied to fn:format-number is not a valid QName, or if the prefix in the QName is undeclared, or if there is no decimal format in the static context with a matching name.

err:FODF1290, Invalid decimal format property.

This error is raised if a decimal format value supplied to fn:format-number is not valid for the associated property, or if the properties of the decimal format resulting from a supplied map do not have distinct values.

err:FODF1310, Invalid decimal format picture string.

This error is raised if the picture string supplied to fn:format-number or fn:format-integer has invalid syntax.

err:FODT0001, Overflow/underflow in date/time operation.

Raised when casting to date/time datatypes, or performing arithmetic with date/time values, if arithmetic overflow or underflow occurs.

err:FODT0002, Overflow/underflow in duration operation.

Raised when casting to duration datatypes, or performing arithmetic with duration values, if arithmetic overflow or underflow occurs.

err:FODT0003, Invalid timezone value.

Raised by adjust-date-to-timezone and related functions if the supplied timezone is invalid.

err:FODT0004, No timezone data available

Raised by civil-timezone if no timezone data is available for the given date/time and place.

err:FOER0000, Unidentified error.

Error code used by fn:error when no other error code is provided.

err:FOFD1340, Invalid date/time formatting parameters.

This error is raised if the picture string or calendar supplied to fn:format-date, fn:format-time, or fn:format-dateTime has invalid syntax.

err:FOFD1350, Invalid date/time formatting component.

This error is raised if the picture string supplied to fn:format-date selects a component that is not present in a date, or if the picture string supplied to fn:format-time selects a component that is not present in a time.

err:FOHA0001, Invalid algorithm.

Raised by fn:hash if the effective value of the supplied algorithm is not one of the values supported by the implementation.

err:FOJS0001, JSON syntax error.

Raised by functions such as fn:json-doc, fn:parse-json or fn:json-to-xml if the string supplied as input does not conform to the JSON grammar (optionally with implementation-defined extensions).

err:FOJS0003, JSON duplicate keys.

Raised by functions such as map:merge, fn:json-doc, fn:parse-json or fn:json-to-xml if the input contains duplicate keys, when the chosen policy is to reject duplicates.

err:FOJS0004, JSON: not schema-aware.

Raised by fn:json-to-xml if validation is requested when the processor does not support schema validation or typed nodes.

err:FOJS0005, Invalid options.

Raised by functions such as map:merge, fn:parse-json, and fn:xml-to-json if the $options map contains an invalid entry.

err:FOJS0006, Invalid XML representation of JSON.

Raised by fn:xml-to-json if the XML input does not conform to the rules for the XML representation of JSON.

err:FOJS0007, Bad JSON escape sequence.

Raised by fn:xml-to-json if the XML input uses the attribute escaped="true" or escaped-key="true", and the corresponding string or key contains an invalid JSON escape sequence.

err:FONS0004, No namespace found for prefix.

Raised by fn:resolve-QName and analogous functions if a supplied QName has a prefix that has no binding to a namespace.

err:FONS0005, Base-uri not defined in the static context.

Raised by fn:resolve-uri if no base URI is available for resolving a relative URI.

err:FOQM0001, Module URI is a zero-length string.

Raised by fn:load-xquery-module if the supplied module URI is zero-length.

err:FOQM0002, Module URI not found.

Raised by fn:load-xquery-module if no module can be found with the supplied module URI.

err:FOQM0003, Static error in dynamically loaded XQuery module.

Raised by fn:load-xquery-module if a static error (including a statically detected type error) is encountered when processing the library module.

err:FOQM0005, Parameter for dynamically loaded XQuery module has incorrect type.

Raised by fn:load-xquery-module if a value is supplied for the initial context item or for an external variable, and the value does not conform to the required type declared in the dynamically loaded module.

err:FOQM0006, No suitable XQuery processor available.

Raised by fn:load-xquery-module if no XQuery processor is available supporting the requested XQuery version (or if none is available at all).

err:FORG0001, Invalid value for cast/constructor.

A general-purpose error raised when casting, if a cast between two datatypes is allowed in principle, but the supplied value cannot be converted: for example when attempting to cast the string "nine" to an integer.

err:FORG0002, Invalid argument to fn:resolve-uri.

Raised when either argument to fn:resolve-uri is not a valid URI/IRI.

err:FORG0003, fn:zero-or-one called with a sequence containing more than one item.

Raised by fn:zero-or-one if the supplied value contains more than one item.

err:FORG0004, fn:one-or-more called with a sequence containing no items.

Raised by fn:one-or-more if the supplied value is an empty sequence.

err:FORG0005, fn:exactly-one called with a sequence containing zero or more than one item.

Raised by fn:exactly-one if the supplied value is not a singleton sequence.

err:FORG0006, Invalid argument type.

Raised by functions such as fn:max, fn:min, fn:avg, fn:sum if the supplied sequence contains values inappropriate to this function.

err:FORG0008, The two arguments to fn:dateTime have inconsistent timezones.

Raised by fn:dateTime if the two arguments both have timezones and the timezones are different.

err:FORG0009, Error in resolving a relative URI against a base URI in fn:resolve-uri.

A catch-all error for fn:resolve-uri, recognizing that the implementation can choose between a variety of algorithms and that some of these may fail for a variety of reasons.

err:FORG0010, Invalid date/time.

Raised when the input to fn:parse-ietf-date does not match the prescribed grammar, or when it represents an invalid date/time such as 31 February.

err:FORG0011, Invalid radix.

Raised when the radix supplied to fn:parse-integer is not in the range 2 to 36.

err:FORG0012, Invalid digits.

Raised when the digits in the string supplied to fn:parse-integer are not in the range appropriate to the chosen radix.

err:FORG0013, Unknown optionInconsistent options.

Raised if the option in an ·option map· is not described in the specification, if it is not supported by the implementation and if its name is in no namespace.

Raised if an inconsistent set of options is supplied in an ·option map·.

err:FORG0013

(Error code unused?)

err:FORX0001, Invalid regular expression flags.

Raised by regular expression functions such as fn:matches and fn:replace if the regular expression flags contain a character other than i, m, q, s, or x.

err:FORX0002, Invalid regular expression.

Raised by regular expression functions such as fn:matches and fn:replace if the regular expression is syntactically invalid.

err:FORX0003, Regular expression matches zero-length string.

For functions such as fn:replace and fn:tokenize, raises an error if the supplied regular expression is capable of matching a zero length string.

err:FORX0004, Invalid replacement string.

Raised by fn:replace to report errors in the replacement string.

err:FORX0005, Incompatible arguments for fn:replace.

Raised by fn:replace if both the $replacement and $action arguments are supplied.

err:FOTY0012, Argument to fn:data contains a node that does not have a typed value.

Raised by fn:data, or by implicit atomization, if applied to a node with no typed value, the main example being an element validated against a complex type that defines it to have element-only content.

err:FOTY0013, The argument to fn:data contains a function item.

Raised by fn:data, or by implicit atomization, if the sequence to be atomized contains a function item other than an array.

err:FOTY0014, The argument to fn:string is a function item.

Raised by fn:string, or by implicit string conversion, if the input sequence contains a function item.

err:FOUR0001, Invalid IPv6/IPvFuture authority

A dynamic error is raised if the authority component of a URI contains an open square bracket but no corresponding close square bracket.

err:FOUT1170, Invalid URI reference.

Raised by fn:unparsed-text or fn:unparsed-text-lines if the $source argument contains a fragment identifier, or if it cannot be resolved to an absolute URI (for example, because the base-URI property in the static context is absent), or if it cannot be used to retrieve the string representation of a resource.

err:FOUT1190, Cannot decode external resource.

Raised by fn:unparsed-text or fn:unparsed-text-lines if the $encoding argument is not a valid encoding name, if the processor does not support the specified encoding, if the string representation of the retrieved resource contains octets that cannot be decoded into Unicode ·characters· using the specified encoding, or if the resulting characters are not ·permitted characters·.

err:FOUT1200, Cannot infer encoding of external resource.

Raised by fn:unparsed-text or fn:unparsed-text-lines if the $encoding argument is absent and the processor cannot infer the encoding using external information and the encoding is not UTF-8.

err:FOXT0001, No suitable XSLT processor available

A dynamic error is raised if no XSLT processor suitable for evaluating a call on fn:transform is available.

err:FOXT0002, Invalid parameters to XSLT transformation

A dynamic error is raised if the parameters supplied to fn:transform are invalid, for example if two mutually exclusive parameters are supplied. If a suitable XSLT error code is available (for example in the case where the requested initial-template does not exist in the stylesheet), that error code should be used in preference.

err:FOXT0003, XSLT transformation failed

A dynamic error is raised if an XSLT transformation invoked using fn:transform fails with a static or dynamic error. The XSLT error code is used if available; this error code provides a fallback when no XSLT error code is returned, for example because the processor is an XSLT 1.0 processor.

err:FOXT0004, XSLT transformation has been disabled

A dynamic error is raised if the fn:transform function is invoked when XSLT transformation (or a specific transformation option) has been disabled for security or other reasons.

err:FOXT0006, XSLT output contains non-accepted characters

A dynamic error is raised if the result of the fn:transform function contains characters available only in XML 1.1 and the calling processor cannot handle such characters.

F Checklist of implementation-defined features (Non-Normative)

It is ·implementation-defined· which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used. (See Conformance.)
It is ·implementation-defined· whether the type system is based on XML Schema 1.0 or XML Schema 1.1. (See Conformance.)
It is ·implementation-defined· whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1. (See Conformance.)
Implementations may attach an ·implementation-defined· meaning to options in the map that are not described in this specification. These options should use values of type xs:QName as the option names, using an appropriate namespace. (See Options.)
It is ·implementation-defined· which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used. (See Strings, characters, and codepoints.)
[Definition] Some functions (such as fn:distinct-values, fn:unordered, map:keys, and map:for-each) produce results in an ·implementation-defined· or ·implementation-dependent· order. In such cases two calls with the same arguments are not guaranteed to produce the results in the same order. These functions are said to be nondeterministic with respect to ordering. (See Properties of functions.)
Where the results of a function are described as being (to a greater or lesser extent) ·implementation-defined· or ·implementation-dependent·, this does not by itself remove the requirement that the results should be deterministic: that is, that repeated calls with the same explicit and implicit arguments must return identical results. (See Properties of functions.)
In addition, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination. (See fn:trace.)
Consider a situation in which a user wants to investigate the actual value passed to a function. Assume that in a particular execution, $v is an xs:decimal with value 124.84. Writing fn:trace($v, 'the value of $v is:') will return $v. The processor may output "124.84" and "the value of $v is:" to an ·implementation-defined· destination. (See fn:trace.)
Similar to fn:trace, the values of $input, typically serialized and converted to an xs:string, and $label (if supplied and non-empty) may be output to an ·implementation-defined· destination. (See fn:message.)
They may provide an ·implementation-defined· mechanism that allows users to choose between raising an error and returning a result that is modulo the largest representable integer value. See [ISO 10967]. (See Arithmetic operators on numeric values.)
For xs:decimal values, let N be the number of digits of precision supported by the implementation, and let M (M <= N) be the minimum limit on the number of digits required for conformance (18 digits for XSD 1.0, 16 digits for XSD 1.1). Then for addition, subtraction, and multiplication operations, the returned result should be accurate to N digits of precision, and for division and modulus operations, the returned result should be accurate to at least M digits of precision. The actual precision is ·implementation-defined·. If the number of digits in the mathematical result exceeds the number of digits that the implementation retains for that operation, the result is truncated or rounded in an ·implementation-defined· manner. (See Arithmetic operators on numeric values.)
The [IEEE 754-2019] specification also describes handling of two exception conditions called divideByZero and invalidOperation. The IEEE divideByZero exception is raised not only by a direct attempt to divide by zero, but also by operations such as log(0). The IEEE invalidOperation exception is raised by attempts to call a function with an argument that is outside the function’s domain (for example, sqrt(-1) or log(-1)). Although IEEE defines these as exceptions, it also defines “default non-stop exception handling” in which the operation returns a defined result, typically positive or negative infinity, or NaN. With this function library, these IEEE exceptions do not cause a dynamic error at the application level; rather they result in the relevant function or operator returning the defined non-error result. The underlying IEEE exception may be notified to the application or to the user by some ·implementation-defined· warning condition, but the observable effect on an application using the functions and operators defined in this specification is simply to return the defined result (typically -INF, +INF, or NaN) with no error. (See Arithmetic operators on numeric values.)
The [IEEE 754-2019] specification distinguishes two NaN values: a quiet NaN and a signaling NaN. These two values are not distinguishable in the XDM model: the value spaces of xs:float and xs:double each include only a single NaN value. This does not prevent the implementation distinguishing them internally, and triggering different ·implementation-defined· warning conditions, but such distinctions do not affect the observable behavior of an application using the functions and operators defined in this specification. (See Arithmetic operators on numeric values.)
The implementation may adopt a different algorithm provided that it is equivalent to this formulation in all cases where ·implementation-dependent· or ·implementation-defined· behavior does not affect the outcome, for example, the implementation-defined precision of the result of xs:decimal division. (See op:numeric-integer-divide.)
There may be ·implementation-defined· limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:round.)
There may be ·implementation-defined· limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:round-half-to-even.)
There may be ·implementation-defined· limits on the precision available. If the requested $precision is outside this range, it should be adjusted to the nearest value supported by the implementation. (See fn:divide-decimals.)
XSD 1.1 allows the string +INF as a representation of positive infinity; XSD 1.0 does not. It is ·implementation-defined· whether XSD 1.1 is supported. (See fn:number.)
Any other format token, which indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is ·implementation-defined· which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1. (See fn:format-integer.)
For all format tokens other than a digit-pattern, there may be ·implementation-defined· lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the format token U+2460 (CIRCLED DIGIT ONE, ①) has a range imposed by the Unicode character repertoire — zero to 20 in Unicode versions prior to 3.2, or zero to 50 in subsequent versions. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1. (See fn:format-integer.)
The set of languages for which numbering is supported is ·implementation-defined·. If the $language argument is absent, or is set to an empty sequence, or is invalid, or is not a language supported by the implementation, then the number is formatted using the default language from the dynamic context. (See fn:format-integer.)
...either a or t, to indicate alphabetic or traditional numbering respectively, the default being ·implementation-defined·. (See fn:format-integer.)
The string of characters between the parentheses, if present, is used to select between other possible variations of cardinal or ordinal numbering sequences. The interpretation of this string is ·implementation-defined·. No error occurs if the implementation does not define any interpretation for the defined string. (See fn:format-integer.)
It is ·implementation-defined· what combinations of values of the format token, the language, and the cardinal/ordinal modifier are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the string appearing in parentheses, the request is ignored and cardinal numbers are generated instead. (See fn:format-integer.)
The use of the a or t modifier disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. In the absence of the a or t modifier, the default is ·implementation-defined·. (See fn:format-integer.)
The static context provides a set of decimal formats. One of the decimal formats is unnamed, the others (if any) are identified by a QName. There is always an unnamed decimal format available, but its contents are ·implementation-defined·. (See Defining a decimal format.)
IEEE states that the preferred quantum is language-defined. In this specification, it is ·implementation-defined·. (See Trigonometric and exponential functions.)
IEEE defines various rounding algorithms for inexact results, and states that the choice of rounding direction, and the mechanisms for influencing this choice, are language-defined. In this specification, the rounding direction and any mechanisms for influencing it are ·implementation-defined·. (See Trigonometric and exponential functions.)
The map returned by the fn:random-number-generator function may contain additional entries beyond those specified here, but it must match the record type defined above. The meaning of any additional entries is ·implementation-defined·. To avoid conflict with any future version of this specification, the keys of any such entries should start with an underscore character. (See fn:random-number-generator.)
If two query parameters use the same keyword then the last one wins. If a query parameter uses a keyword or value which is not defined in this specification then the meaning is ·implementation-defined·. If the implementation recognizes the meaning of the keyword and value then it should interpret it accordingly; if it does not recognize the keyword or value then if the fallback parameter is present with the value no it should reject the collation as unsupported, otherwise it should ignore the unrecognized parameter. (See The Unicode Collation Algorithm.)
The following query parameters are defined. If any parameter is absent, the default is ·implementation-defined· except where otherwise stated. The meaning given for each parameter is non-normative; the normative specification is found in [UTS #35]. (See The Unicode Collation Algorithm.)
Because the set of collations that are supported is ·implementation-defined·, an implementation has the option to support all collation URIs, in which case it will never raise this error. (See Choosing a collation.)
The properties available are as defined for the Unicode Collation Algorithm (see 5.3.4 The Unicode Collation Algorithm). Additional ·implementation-defined· properties may be specified as described in the rules for UCA collation URIs. (See fn:collation.)
It is possible to define collations that do not have the ability to generate collation keys. Supplying such a collation will cause the function to fail. The ability to generate collation keys is an ·implementation-defined· property of the collation. (See fn:collation-key.)
Conforming implementations must support normalization form NFC and may support normalization forms NFD, NFKC, NFKD, and FULLY-NORMALIZED. They may also support other normalization forms with ·implementation-defined· semantics. (See fn:normalize-unicode.)
It is ·implementation-defined· which version of Unicode (and therefore, of the normalization algorithms and their underlying data) is supported by the implementation. See [UAX #15] for details of the stability policy regarding changes to the normalization rules in future versions of Unicode. If the input string contains codepoints that are unassigned in the relevant version of Unicode, or for which no normalization rules are defined, the fn:normalize-unicode function leaves such codepoints unchanged. If the implementation supports the requested normalization form then it must be able to handle every input string without raising an error. (See fn:normalize-unicode.)
It is possible to define collations that do not have the ability to decompose a string into units suitable for substring matching. An argument to a function defined in this section may be a URI that identifies a collation that is able to compare two strings, but that does not have the capability to split the string into collation units. Such a collation may cause the function to fail, or to give unexpected results, or it may be rejected as an unsuitable argument. The ability to decompose strings into collation units is an ·implementation-defined· property of the collation. The fn:collation-available function can be used to ask whether a particular collation has this property. (See Functions based on substring matching.)
The result of the function will always be such that validation against this schema would succeed. However, it is ·implementation-defined· whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:analyze-string.)
Some URI schemes are hierarchical and some are non-hierarchical. Implementations must treat the following schemes as non-hierarchical: jar, mailto, news, tag, tel, and urn. Whether additional schemes are known to be non-hierarchical ·implementation-defined·. If a scheme is not known to be non-hierarchical, it must be treated as hierarchical. (See Parsing and building URIs.)
If the omit-default-ports option is true, the port is discarded and set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is ·implementation-defined·. (See fn:parse-uri.)
If the omit-default-ports option is true then the $port is set to the empty sequence if the port number is the same as the default port for the given scheme. Implementations should recognize the default ports for http (80), https (443), ftp (21), and ssh (22). Exactly which ports are recognized is ·implementation-defined·. (See fn:build-uri.)
Processors may support a greater range and/or precision. The limits are ·implementation-defined·. (See Limits and precision.)
Similarly, a processor may be unable accurately to represent the result of dividing a duration by 2, or multiplying a duration by 0.5. A processor that limits the precision of the seconds component of duration values must deliver a result that is as close as possible to the mathematically precise result, given these limits; if two values are equally close, the one that is chosen is ·implementation-defined·. (See Limits and precision.)
All conforming processors must support year values in the range 1 to 9999, and a minimum fractional second precision of 1 millisecond or three digits (i.e., s.sss). However, processors may set larger ·implementation-defined· limits on the maximum number of digits they support in these two situations. Processors may also choose to support the year 0 and years with negative values. The results of operations on dates that cross the year 0 are ·implementation-defined·. (See Limits and precision.)
Similarly, a processor that limits the precision of the seconds component of date and time or duration values may need to deliver a rounded result for arithmetic operations. Such a processor must deliver a result that is as close as possible to the mathematically precise result, given these limits: if two values are equally close, the one that is chosen is ·implementation-defined·. (See Limits and precision.)
...the format token n, N, or Nn, indicating that the value of the component is to be output by name, in lower-case, upper-case, or title-case respectively. Components that can be output by name include (but are not limited to) months, days of the week, timezones, and eras. If the processor cannot output these components by name for the chosen calendar and language then it must use an ·implementation-defined· fallback representation. (See The picture string.)
...indicates alphabetic or traditional numbering respectively, the default being ·implementation-defined·. This has the same meaning as in the second argument of fn:format-integer. (See The picture string.)
The sequence of characters in the (adjusted) first presentation modifier is reversed (for example, 999'### becomes ###'999). If the result is not a valid decimal digit pattern, then the output is ·implementation-defined·. (See Formatting Fractional Seconds.)
The output for these components is entirely ·implementation-defined·. The default presentation modifier for these components is n, indicating that they are output as names (or conventional abbreviations), and the chosen names will in many cases depend on the chosen language: see 9.8.4.8 The language, calendar, and place arguments. (See Formatting Other Components.)
The set of languages, calendars, and places that are supported in the ·date formatting functions· is ·implementation-defined·. When any of these arguments is omitted or is an empty sequence, an ·implementation-defined· default value is used. (See The language, calendar, and place arguments.)
The choice of the names and abbreviations used in any given language is ·implementation-defined·. For example, one implementation might abbreviate July as Jul while another uses Jly. In German, one implementation might represent Saturday as Samstag while another uses Sonnabend. Implementations may provide mechanisms allowing users to control such choices. (See The language, calendar, and place arguments.)
The choice of the names and abbreviations used in any given language for calendar units such as days of the week and months of the year is ·implementation-defined·. (See The language, calendar, and place arguments.)
The calendar value if present must be a valid EQName (dynamic error: [err:FOFD1340]). If it is a lexical QName then it is expanded into an expanded QName using the statically known namespaces; if it has no prefix then it represents an expanded-QName in no namespace. If the expanded QName is in no namespace, then it must identify a calendar with a designator specified below (dynamic error: [err:FOFD1340]). If the expanded QName is in a namespace then it identifies the calendar in an ·implementation-defined· way. (See The language, calendar, and place arguments.)
At least one of the above calendars must be supported. It is ·implementation-defined· which calendars are supported. (See The language, calendar, and place arguments.)
The requirement to deliver a deterministic result has performance implications, and for this reason implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call of the function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:doc.)
Various aspects of this processing are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:doc.)
It is ·implementation-defined· whether DTD validation and/or schema validation is applied to the source document. (See fn:doc.)
The effect of a fragment identifier in the supplied URI is ·implementation-defined·. One possible interpretation is to treat the fragment identifier as an ID attribute value, and to return a document node having the element with the selected ID value as its only child. (See fn:doc.)
By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:collection.)
By default, this function is ·deterministic·. This means that repeated calls on the function with the same argument will return the same result. However, for performance reasons, implementations may provide a user option to evaluate the function without a guarantee of determinism. The manner in which any such option is provided is ·implementation-defined·. If the user has not selected such an option, a call to this function must either return a deterministic result or must raise a dynamic error [err:FODC0003]. (See fn:uri-collection.)
...the processor may use ·implementation-defined· heuristics to determine the likely encoding, otherwise... (See fn:unparsed-text.)
The fact that the resolution of URIs is defined by a mapping in the dynamic context means that in effect, various aspects of the behavior of this function are ·implementation-defined·. Implementations may provide external configuration options that allow any aspect of the processing to be controlled by the user. In particular:... (See fn:unparsed-text.)
The collation used for matching names is ·implementation-defined·, but must be the same as the collation used to ensure that the names of all environment variables are unique. (See fn:environment-variable.)
Except to the extent defined by these options, the precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml.)
Except as explicitly defined, the precise process used to construct the XDM instance is ·implementation-defined·. In particular, it is implementation-defined whether an XML 1.0 or XML 1.1 parser is used. (See fn:parse-xml-fragment.)
If the second argument is omitted, or is supplied in the form of an output:serialization-parameters element, then the values of any serialization parameters that are not explicitly specified is ·implementation-defined·, and may depend on the context. (See fn:serialize.)
Because the [DOM: Living Standard] and [HTML: Living Standard] are not fixed, it is ·implementation-defined· which versions are used. (See XDM Mapping from HTML DOM Nodes.)
If an implementation allows these nodes to be passed in via an API or similar mechanism, their behaviour is ·implementation-defined·. (See XDM Mapping from HTML DOM Nodes.)
If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an ·implementation-defined· replacement string is used. The result must be a valid NCName. (See node-name Accessor.)
If the local name contains a character that is not a valid XML NameStartChar or NameChar, then an ·implementation-defined· replacement string is used. The result must be a valid NCName. (See node-name Accessor.)
Additional ·implementation-defined· parser options are allowed. (See HTML parser options.)
Any other method and html-version combinations are ·implementation-defined·. (See fn:parse-html.)
The default behaviour is ·implementation-defined·. (See fn:parse-html.)
An ·implementation-defined· parsing algorithm, tree construction, and validation consistent with the specified HTML version. (See fn:parse-html.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised [err:FOJS0001] if the input does not conform to the grammar. (See fn:parse-json.)
The supplied function is called to process the string value of any JSON number in the input. By default, numbers are processed by converting to xs:double using the XPath casting rules. Supplying the value xs:decimal#1 will instead convert to xs:decimal (which potentially retains more precision, but disallows exponential notation), while supplying a function that casts to (xs:decimal | xs:double) will treat the value as xs:decimal if there is no exponent, or as xs:double otherwise. Supplying the value fn:identity#1 causes the value to be retained unchanged as an xs:untypedAtomic. If the liberal option is false (the default), then the supplied number-parser is called if and only if the value conforms to the JSON grammar for numbers (for example, a leading plus sign and redundant leading zeroes are not allowed). If the liberal option is true then it is also called if the value conforms to an ·implementation-defined· extension of this grammar. (See fn:parse-json.)
The input may contain deviations from the grammar of [RFC 7159], which are handled in an ·implementation-defined· way. (Note: some popular extensions include allowing quotes on keys to be omitted, allowing a comma to appear after the last item in an array, allowing leading zeroes in numbers, and allowing control characters such as tab and newline to be present in unescaped form.) Since the extensions accepted are implementation-defined, an error may be raised (see below) if the input does not conform to the grammar. (See fn:json-to-xml.)
Default: ·Implementation-defined·. (See fn:json-to-xml.)
Indicates that the resulting XDM instance must be typed; that is, the element and attribute nodes must carry the type annotations that result from validation against the schema given at C.2 Schema for the result of fn:json-to-xml, or against an ·implementation-defined· schema if the liberal option has the value true. (See fn:json-to-xml.)
The result of the function will always be such that validation against this schema would succeed. However, it is ·implementation-defined· whether the result is typed or untyped, that is, whether the elements and attributes in the returned tree have type annotations that reflect the result of validating against this schema. (See fn:csv-to-xml.)
Additional, ·implementation-defined· options may be available, for example, to control aspects of the XML serialization, to specify the grammar start symbol, or to produce output formats other than XML. (See fn:invisible-xml.)
If the arguments to fn:function-lookup identify a function that is present in the static context of the function call, the function will always return the same function that a static reference to this function would bind to. If there is no such function in the static context, then the results depend on what is present in the dynamic context, which is ·implementation-defined·. (See fn:function-lookup.)
Default: The version given in the prolog of the library module; or ·implementation-defined· if this is absent. (See fn:load-xquery-module.)
A sequence of URIs (in the form of xs:string values) which may be used or ignored in an ·implementation-defined· way.... (See fn:load-xquery-module.)
Values for vendor-defined configuration options for the XQuery processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XQuery processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. The ·option parameter conventions· do not apply to this contained map.... (See fn:load-xquery-module.)
It is ·implementation-defined· whether constructs in the library module are evaluated in the same ·execution scope· as the calling module. (See fn:load-xquery-module.)
The library module that is loaded may import schema declarations using an import schema declaration. It is ·implementation-defined· whether schema components in the in-scope schema definitions of the calling module are automatically added to the in-scope schema definitions of the dynamically loaded module. The in-scope schema definitions of the calling and called modules must be consistent, according to the rules defined in Section 2.2.5 Consistency Constraints ^XQ31. (See fn:load-xquery-module.)
Default: ·Implementation-defined·. (See fn:transform.)
Default: ·Implementation-defined·. (See fn:transform.)
If the implementation provides a way of writing or invoking functions with side-effects, this post-processing function might be used to save a copy of the result document to persistent storage. For example, if the implementation provides access to the EXPath File library [EXPath], then a serialized document might be written to filestore by calling the file:write function. Similar mechanisms might be used to issue an HTTP POST request that posts the result to an HTTP server, or to send the document to an email recipient. The semantics of calling functions with side-effects are entirely ·implementation-defined·. (See fn:transform.)
Calls to fn:transform can potentially have side-effects even in the absence of the post-processing option, because the XSLT specification allows a stylesheet to invoke extension functions that have side-effects. The semantics in this case are ·implementation-defined·. (See fn:transform.)
A string intended to be used as the static base URI of the principal stylesheet module. This value must be used if no other static base URI is available. If the supplied stylesheet already has a base URI (which will generally be the case if the stylesheet is supplied using stylesheet-node or stylesheet-location) then it is ·implementation-defined· whether this parameter has any effect. If the value is a relative reference, it is resolved against the static base URI of the fn:transform function call.... (See fn:transform.)
Values for vendor-defined configuration options for the XSLT processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is ·implementation-defined·. Implementations should ignore options whose names are in an unrecognized namespace. Default is an empty map.... (See fn:transform.)
It is ·implementation-defined· whether the XSLT transformation is executed within the same ·execution scope· as the calling code. (See fn:transform.)
XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an ·implementation-defined· way. (See fn:transform.)
The key of the combined entry is taken from one of the duplicate entries: it is ·implementation-defined· which one is used. (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 with different timezones.) ... (See map:build.)
The key of the combined entry is taken from one of the duplicate entries: it is ·implementation-defined· which one is used. (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 with different timezones.) ... (See map:build.)
The key of the combined entry is one of the duplicate keys: which one is chosen is ·implementation-defined·. (Two keys that are deemed duplicates may differ: for example they may have different type annotations, or they may be xs:dateTime values with different timezones.)... (See map:merge.)
The key of the combined entry is one of the duplicate keys: which one is chosen is ·implementation-defined·. (Two keys that are deemed duplicates may differ: for example they may have different type annotations, or they may be xs:dateTime values with different timezones.)... (See map:merge.)
Equivalent to specifying "combine": fn(){error(xs:QName("err:FOJS0003"), ...) (the remaining arguments to fn:error being ·implementation-defined·). (See map:merge.)
Equivalent to specifying "combine": fn(){error(xs:QName("err:FOJS0003"), ...) (the remaining arguments to fn:error being ·implementation-defined·). (See map:merge.)
Equivalent to specifying "combine": fn($a, $b){ one-of($a, $b) } where one-of chooses either $a or $b in an ·implementation-defined· way. (See map:merge.)
Equivalent to specifying "combine": fn($a, $b){ one-of($a, $b) } where one-of chooses either $a or $b in an ·implementation-defined· way. (See map:merge.)
If ST is xs:float or xs:double, then TV is the xs:decimal value, within the set of xs:decimal values that the implementation is capable of representing, that is numerically closest to SV. If two values are equally close, then the one that is closest to zero is chosen. If SV is too large to be accommodated as an xs:decimal, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0001]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:decimal.)
In casting to xs:decimal or to a type derived from xs:decimal, if the value is not too large or too small but nevertheless cannot be represented accurately with the number of decimal digits available to the implementation, the implementation may round to the nearest representable value or may raise a dynamic error [err:FOCA0006]. The choice of rounding algorithm and the choice between rounding and error behavior is ·implementation-defined·. (See Casting from xs:string and xs:untypedAtomic.)
If ST is xs:decimal, xs:float or xs:double, then TV is SV with the fractional part discarded and the value converted to xs:integer. Thus, casting 3.1456 returns 3 while -17.89 returns -17. Casting 3.124E1 returns 31. If SV is too large to be accommodated as an integer, (see [XML Schema Part 2: Datatypes Second Edition] for ·implementation-defined· limits on numeric values) a dynamic error is raised [err:FOCA0003]. If SV is one of the special xs:float or xs:double values NaN, INF, or -INF, a dynamic error is raised [err:FOCA0002]. (See Casting to xs:integer.)
The tz timezone database, available at http://www.iana.org/time-zones. It is ·implementation-defined· which version of the database is used. (See IANA Timezone Database.)
Unicode Standard Annex #15: Unicode Normalization Forms. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-02-24. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr15/. (See UAX #15.)
Unicode Standard Annex #29: Unicode Text Segmentation. Ed. Josh Hadley, Unicode Consortium. The current version is 15.1.0, dated 2023-08-16. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr29/. (See UAX #29.)
The Unicode Consortium, Reading, MA, Addison-Wesley, 2016. The Unicode Standard as updated from time to time by the publication of new versions. See http://www.unicode.org/standard/versions/ for the latest version and additional information on versions of the standard and of the Unicode Character Database. The version of Unicode to be used is ·implementation-defined·, but implementations are recommended to use the latest Unicode version; currently, Version 9.0.0. (See The Unicode Standard.)
Unicode Technical Standard #10: Unicode Collation Algorithm. Ed. Mark Davis and Ken Whistler, Unicode Consortium. The current version is 9.0.0, dated 2016-05-18. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr10/. (See UTS #10.)
Unicode Technical Standard #35: Unicode Locale Data Markup Language. Ed Mark Davis et al, Unicode Consortium. The current version is 29, dated 2016-03-15. As with [The Unicode Standard], the version to be used is ·implementation-defined·. Available at: http://www.unicode.org/reports/tr35/. (See UTS #35.)

G Changes since version 3.1 (Non-Normative)

G.1 Summary of Changes

Use the arrows to browse significant changes since the 3.1 version of this specification.
See 1 Introduction
Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.
See 1 Introduction
PR 1547 1551
New in 4.0
See 2.2.8 fn:siblings
PR 629 803
New in 4.0
See 3.2.2 fn:message
PR 1260 1275
A third argument has been added, providing control over the rounding mode.
See 4.4.4 fn:round
New in 4.0
See 4.4.7 fn:is-NaN
PR 1049 1151
Decimal format parameters can now be supplied directly as a map in the third argument, rather than referencing a format defined in the static context.
See 4.7.2 fn:format-number
PR 1205 1230
New in 4.0
See 4.8.2 math:e
See 4.8.16 math:sinh
See 4.8.17 math:cosh
See 4.8.18 math:tanh
The 3.1 specification suggested that every value in the result range should have the same chance of being chosen. This has been corrected to say that the distribution should be arithmetically uniform (because there are as many xs:double values between 0.01 and 0.1 as there are between 0.1 and 1.0).
See 4.9.2 fn:random-number-generator
PR 261 306 993
New in 4.0
See 5.4.1 fn:char
New in 4.0
See 5.4.2 fn:characters
PR 937 995 1190
New in 4.0
See 5.4.13 fn:hash
The $action argument is new in 4.0.
See 5.6.4 fn:replace
New in 4.0
See 6.6.2 fn:parse-uri
PR 1423 1413
New in 4.0
See 6.6.3 fn:build-uri
New in 4.0
See 10.2.6 fn:in-scope-namespaces
Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.
See 10.2.7 fn:in-scope-prefixes
Reformulated in 4.0 in terms of the new fn:in-scope-namespaces function; the semantics are unchanged.
See 10.2.8 fn:namespace-uri-for-prefix
New in 4.0
See 13.1.9 fn:replicate
New in 4.0
See 13.1.12 fn:slice
New in 4.0. The function is identical to the internal op:same-key function in 3.1
See 13.2.1 fn:atomic-equal
PR 1120 1150
A callback function can be supplied for comparing individual items.
See 13.2.2 fn:deep-equal
Changed in 4.0 to use transitive equality comparisons for numeric values.
See 13.2.4 fn:distinct-values
New in 4.0. Originally proposed under the name fn:uniform
See 13.4.6 fn:all-equal
New in 4.0. Originally proposed under the name fn:unique
See 13.4.7 fn:all-different
PR 1117 1279
The $options parameter has been added.
See 13.6.6 fn:unparsed-text-lines
A new function is available for processing input data in HTML format.
See 14.2 Functions on HTML Data
PR 259 956
New in 4.0
See 14.2.3 fn:parse-html
PR 975 1058 1246
An option is provided to control how JSON numbers should be formatted.
See 14.3.4 fn:parse-json
Additional options are available, as defined by fn:parse-json.
See 14.3.5 fn:json-doc
PR 533 719 834 1066
New in 4.0
See 14.4.4 fn:csv-to-arrays
See 14.4.7 fn:parse-csv
PR 533 719 834 1066 1605
New in 4.0
See 14.4.9 fn:csv-to-xml
PR 791 1256 1282 1405
New in 4.0
See 14.5.1 fn:invisible-xml
New in 4.0
See 16.2.4 fn:every
New in 4.0
See 16.2.10 fn:highest
New in 4.0
See 16.2.11 fn:index-where
New in 4.0
See 16.2.12 fn:lowest
New in 4.0
See 16.2.15 fn:scan-right
New in 4.0
See 16.2.16 fn:some
PR 521 761
New in 4.0
See 16.2.21 fn:transitive-closure
New in 4.0
See 17.4.6 map:filter
A third argument is added, allowing user control of how absent keys should be handled.
See 17.4.9 map:get
New in 4.0
See 17.4.10 map:items
PR 478 515
New in 4.0
See 17.4.12 map:keys-where
New in 4.0
See 17.4.14 map:of-pairs
New in 4.0
See 17.4.15 map:pair
New in 4.0
See 17.4.16 map:pairs
New in 4.0
See 17.4.19 map:replace
New in 4.0.
See 17.5.7 fn:elements-to-maps
New in 4.0
See 18.2.3 array:empty
A third argument is added, allowing user control of how index-out-of-bounds conditions should be handled.
See 18.2.11 array:get
PR 968 1295
New in 4.0
See 18.2.13 array:index-of
PR 476 1087
New in 4.0
See 18.2.16 array:items
PR 360 476
New in 4.0
See 18.2.18 array:members
See 18.2.19 array:of-members
New in 4.0
See 18.2.22 array:replace
New in 4.0
See 18.2.25 array:slice
New in 4.0
See 18.2.26 array:sort
New in 4.0
See 18.2.27 array:split
Supplying an empty sequence as the value of an optional argument is equivalent to omitting the argument.
See 18.2.28 array:subarray
New functions are provided to obtain information about built-in types and types defined in an imported schema.
See 19 Functions on types
Options are added to customize the form of the output.
See 2.2.6 fn:path
PR 533 719 834
New functions are available for processing input data in CSV (comma separated values) format.
See 14.4 Functions on CSV Data
PR 734 1233
New in 4.0
See 16.2.2 fn:chain
A new function fn:elements-to-maps is provided for converting XDM trees to maps suitable for serialization as JSON. Unlike the fn:xml-to-json function retained from 3.1, this can handle arbitrary XML as input.
See 17.5 Converting Elements to Maps
New in 4.0
See 13.1.5 fn:identity
New in 4.0.
See 4.4.6 fn:divide-decimals
The default for the escape option has been changed to false. The 3.1 specification gave the default value as true, but this appears to have been an error, since it was inconsistent with examples given in the specification and with tests in the test suite.
See 14.3.4 fn:parse-json
The spec has been corrected to note that the function depends on the implicit timezone.
See 13.2.3 fn:compare
It is explicitly stated that the limits for $precision are implementation-defined.
See 4.4.4 fn:round
See 4.4.5 fn:round-half-to-even
For consistency with the new functions map:build and map:of-pairs, the handling of duplicates may now be controlled by the combine option as an alternative to the existing duplicates option.
See 17.4.13 map:merge
For consistency with the new functions map:build and map:of-pairs, the handling of duplicates may now be controlled by the combine option as an alternative to the existing duplicates option.
See 17.4.13 map:merge
PR 173
New in 4.0
See 16.3.4 fn:op
PR 203
New in 4.0
See 17.4.1 map:build
PR 207
New in 4.0
See 10.1.2 fn:parse-QName
See 10.2.5 fn:expanded-QName
PR 222
New in 4.0
See 13.2.7 fn:starts-with-subsequence
See 13.2.8 fn:ends-with-subsequence
See 13.2.9 fn:contains-subsequence
PR 250
New in 4.0
See 13.1.3 fn:foot
See 13.1.15 fn:trunk
See 18.2.2 array:build
See 18.2.8 array:foot
See 18.2.30 array:trunk
PR 258
New in 4.0
See 18.2.14 array:index-where
PR 313
The second argument can now be a sequence of integers.
See 13.1.8 fn:remove
PR 314
New in 4.0
See 17.4.4 map:entries
PR 326
Higher-order functions are no longer an optional feature.
See 1.2 Conformance
PR 419
New in 4.0
See 13.1.7 fn:items-at
PR 434
New in 4.0
See 4.5.2 fn:parse-integer
The function has been extended to allow output in a radix other than 10, for example in hexadecimal.
See 4.6.1 fn:format-integer
PR 482
Deleted an inaccurate statement concerning the behavior of NaN.
See 4.3 Comparison operators on numeric values
PR 507
New in 4.0
See 16.2.13 fn:partition
PR 546
The rules regarding use of non-XML characters in JSON texts have been relaxed.
See 14.3.3 JSON character repertoire
See 14.3.4 fn:parse-json
PR 614
New in 4.0
See 13.2.5 fn:duplicate-values
PR 623
Substantially revised to allow multiple sort key definitions.
See 16.2.17 fn:sort
PR 631
New in 4.0
See 6.3 fn:decode-from-uri
PR 662
Constructor functions now have a zero-arity form; the first argument defaults to the context item.
See 20 Constructor functions
PR 680
The case-insensitive collation is now defined normatively within this specification, rather than by reference to the HTML "living specification", which is subject to change. The collation can now be used for ordering comparisons as well as equality comparisons.
See 5.3.5 The HTML ASCII Case-Insensitive Collation
PR 702
The function can now take any number of arguments (previously it had to be two or more), and the arguments can be sequences of strings rather than single strings.
See 5.4.4 fn:concat
PR 710
Changes the function to return a sequence of key-value pairs rather than a map.
See 16.1.4 fn:function-annotations
PR 727
It has been clarified that loading a module has no effect on the static or dynamic context of the caller.
See 16.3.2 fn:load-xquery-module
PR 795
New in 4.0
See 16.2.18 fn:sort-with
PR 828
The $predicate callback function accepts an optional position argument.
See 16.2.5 fn:filter
See 16.2.6 fn:fold-left
The $action callback function accepts an optional position argument.
See 16.2.7 fn:fold-right
See 16.2.8 fn:for-each
See 16.2.9 fn:for-each-pair
The $predicate callback function now accepts an optional position argument.
See 18.2.4 array:filter
The $action callback function now accepts an optional position argument.
See 18.2.6 array:fold-left
See 18.2.7 array:fold-right
See 18.2.9 array:for-each
See 18.2.10 array:for-each-pair
PR 881
The way that fn:min and fn:max compare numeric values of different types has changed. The most noticeable effect is that when these functions are applied to a sequence of xs:integer or xs:decimal values, the result is an xs:integer or xs:decimal, rather than the result of converting this to an xs:double
See 13.4.3 fn:max
See 13.4.4 fn:min
PR 901
All three arguments are now optional, and each argument can be set to an empty sequence. Previously if $description was supplied, it could not be empty.
See 3.1.1 fn:error
The $label argument can now be set to an empty sequence. Previously if $label was supplied, it could not be empty.
See 3.2.1 fn:trace
The third argument can now be supplied as an empty sequence.
See 5.4.6 fn:substring
The second argument can now be an empty sequence.
See 5.6.5 fn:tokenize
The optional second argument can now be supplied as an empty sequence.
See 6.1 fn:resolve-uri
The 3rd, 4th, and 5th arguments are now optional; previously the function required either 2 or 5 arguments.
See 9.8.1 fn:format-dateTime
See 9.8.2 fn:format-date
See 9.8.3 fn:format-time
The optional third argument can now be supplied as an empty sequence.
See 13.1.13 fn:subsequence
PR 905
The rule that multiple calls on fn:doc supplying the same absolute URI must return the same document node has been clarified; in particular the rule does not apply if the dynamic context for the two calls requires different processing of the documents (such as schema validation or whitespace stripping).
See 13.6.1 fn:doc
PR 909
The function has been expanded in scope to handle comparison of values other than strings.
See 13.2.3 fn:compare
PR 924
Rules have been added clarifying that users should not be allowed to change the schema for the fn namespace.
See C Schemas
PR 925
The decimal format name can now be supplied as a value of type xs:QName, as an alternative to supplying a lexical QName as an instance of xs:string.
See 4.7.2 fn:format-number
PR 932
The specification now prescribes a minimum precision and range for durations.
See 8.1.2 Limits and precision
PR 933
When comments and processing instructions are ignored, any text nodes either side of the comment or processing instruction are now merged prior to comparison.
See 13.2.2 fn:deep-equal
PR 940
New in 4.0
See 16.2.19 fn:subsequence-where
PR 953
Constructor functions for named record types have been introduced.
See 20.6 Constructor functions for named record types
PR 962
New in 4.0
See 16.2.3 fn:do-until
See 16.2.22 fn:while-do
PR 969
New in 4.0
See 17.4.3 map:empty
PR 984
New in 4.0
See 8.4.1 fn:seconds
PR 987
The order of results is now prescribed; it was previously implementation-dependent.
See 13.2.4 fn:distinct-values
See 13.2.5 fn:duplicate-values
PR 988
New in 4.0
See 14.3.8 fn:pin
See 14.3.9 fn:label
PR 1022
Regular expressions can include comments (starting and ending with #) if the c flag is set.
See 5.6.1 Regular expression syntax
See 5.6.2 Flags
PR 1028
An option is provided to control how the JSON null value should be handled.
See 14.3.4 fn:parse-json
PR 1032
New in 4.0
See 13.1.17 fn:void
PR 1046
New in 4.0
See 16.2.20 fn:take-while
PR 1059
Use of an option keyword that is not defined in the specification and is not known to the implementation now results in a dynamic error; previously it was ignored.
See 1.7 Options
PR 1068
New in 4.0
See 5.4.3 fn:graphemes
PR 1072
The return type is now specified more precisely.
See 16.3.2 fn:load-xquery-module
PR 1090
When casting from a string to a duration or time or dateTime, it is now specified that when there are more digits in the fractional seconds than the implementation is able to retain, excess digits are truncated. Rounding upwards (which could affect the number of minutes or hours in the value) is not permitted.
See 21.2 Casting from xs:string and xs:untypedAtomic
PR 1093
New in 4.0
See 5.3.8 fn:collation
PR 1117
The $options parameter has been added.
See 13.6.5 fn:unparsed-text
See 13.6.7 fn:unparsed-text-available
PR 1182
The $predicate callback function may return an empty sequence (meaning false).
See 16.2.3 fn:do-until
See 16.2.4 fn:every
See 16.2.5 fn:filter
See 16.2.6 fn:fold-left
See 16.2.11 fn:index-where
See 16.2.16 fn:some
See 16.2.20 fn:take-while
See 16.2.22 fn:while-do
See 17.4.6 map:filter
See 17.4.12 map:keys-where
See 18.2.4 array:filter
See 18.2.14 array:index-where
PR 1191
New in 4.0
See 2.3.1 fn:distinct-ordered-nodes
The $options parameter has been added, absorbing the $collation parameter.
See 13.2.2 fn:deep-equal
PR 1250
For selected properties including percent and exponent-separator, it is now possible to specify a single-character marker to be used in the picture string, together with a multi-character rendition to be used in the formatted output.
See 4.7.2 fn:format-number
PR 1257
The $options parameter has been added.
See 14.1.1 fn:parse-xml
See 14.1.2 fn:parse-xml-fragment
PR 1262
New in 4.0
See 5.3.9 fn:collation-available
PR 1265
The constraints on the result of the function have been relaxed.
See 2.1.6 fn:document-uri
PR 1280
As a result of changes to the coercion rules, the number of supplied arguments can be greater than the number required: extra arguments are ignored.
See 16.2.1 fn:apply
PR 1288
Additional error conditions have been defined.
See 14.1.1 fn:parse-xml
PR 1296
New in 4.0
See 16.2.14 fn:scan-left
PR 1333
A new option is provided to allow the content of the loaded module to be supplied as a string.
See 16.3.2 fn:load-xquery-module
PR 1353
An option has been added to suppress the escaping of the solidus (forwards slash) character.
See 14.3.7 fn:xml-to-json
PR 1358
New in 4.0
See 9.3.2 fn:unix-dateTime
PR 1361
The term atomic value has been replaced by atomic item.
See 1.9 Terminology
PR 1393
Changes the function to return a sequence of key-value pairs rather than a map.
See 16.1.4 fn:function-annotations
PR 1409
This section now uses the term primitive type strictly to refer to the 20 atomic types that are not derived by restriction from another atomic type: that is, the 19 primitive atomic types defined in XSD, plus xs:untypedAtomic. The three types xs:integer, xs:dayTimeDuration, and xs:yearMonthDuration, which have custom casting rules but are not strictly-speaking primitive, are now handled in other subsections.
See 21.1 Casting from primitive types to primitive types
The rules for conversion of dates and times to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since these deliver exactly the same result as the XPath 3.1 rules.
See 21.1.2.2 Casting date/time values to xs:string
The rules for conversion of durations to strings are now defined entirely in terms of XSD 1.1 canonical mappings, since the XSD 1.1 rules deliver exactly the same result as the XPath 3.1 rules.
See 21.1.2.3 Casting xs:duration values to xs:string
PR 1455
Numbers now retain their original lexical form, except for any changes needed to satisfy JSON syntax rules (for example, stripping leading zero digits).
See 14.3.7 fn:xml-to-json
PR 1481
The function has been extended to handle other Gregorian types such as xs:gYearMonth.
See 9.5.1 fn:year-from-dateTime
See 9.5.2 fn:month-from-dateTime
The function has been extended to handle other Gregorian types such as xs:gMonthDay.
See 9.5.3 fn:day-from-dateTime
The function has been extended to handle other types including xs:time.
See 9.5.4 fn:hours-from-dateTime
See 9.5.5 fn:minutes-from-dateTime
The function has been extended to handle other types such as xs:gYearMonth.
See 9.5.7 fn:timezone-from-dateTime
PR 1504
New in 4.0
See 13.1.11 fn:sequence-join
Optional $separator added.
See 18.2.17 array:join
PR 1523
New in 4.0
See 19.1.2 fn:schema-type
See 19.1.4 fn:atomic-type-annotation
See 19.1.5 fn:node-type-annotation
PR 1545
New in 4.0
See 9.6.4 fn:civil-timezone
PR 1570
New in 4.0
See 19.1.3 fn:type-of
PR 1703
The order of entries in maps is retained.
See 14.3.4 fn:parse-json
Ordered maps are introduced.
See 17.1 Ordering of Maps
Enhanced to allow for ordered maps.
See 17.4.6 map:filter
See 17.4.7 map:find
See 17.4.8 map:for-each
See 17.4.17 map:put
See 17.4.18 map:remove

XPath and XQuery Functions and Operators 4.0

W3C Editor's Draft 23 February 2026

Abstract

Status of this Document

Dedication

17 Maps

17.4 Functions that Operate on Maps

17.4.1 map:build

17.4.13 map:merge

17.4.14 map:of-pairs

B Error summary

F Checklist of implementation-defined features (Non-Normative)

G Changes since version 3.1 (Non-Normative)

G.1 Summary of Changes