Map Module

This XQuery Module contains functions for manipulating maps. Maps have been introduced with XQuery 3.1.

Conventions

All functions in this module are assigned to the http://www.w3.org/2005/xpath-functions/map namespace, which is statically bound to the map prefix.

Functions

Some examples use the map $week defined as:

declare variable $week := map {
  0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat"
};

map:contains

Signature	map:contains( $map as map(*), $key as xs:anyAtomicType ) as xs:boolean
Summary	Returns true if the supplied $map contains an entry with a key equal to the supplied value of $key; otherwise it returns false. No error is raised if the map contains keys that are not comparable with the supplied $key. If the supplied key is xs:untypedAtomic, it is compared as an instance of xs:string. If the supplied key is the xs:float or xs:double value NaN, the function returns true if there is an entry whose key is NaN, or false otherwise.
Examples	map:contains($week, 2) returns true(). map:contains($week, 9) returns false(). map:contains(map {}, "xyz") returns false(). map:contains(map { "xyz": 23 }, "xyz") returns true().

map:entry

Signature	map:entry( $key as xs:anyAtomicType, $value as item()* ) as map(*)
Summary	Creates a new map containing a single entry. The key of the entry in the new map is $key, and its associated value is $value. The function map:entry is intended primarily for use in conjunction with the function map:merge. For example, a map containing seven entries may be constructed like this: map:merge(( map:entry("Sun", "Sunday"), map:entry("Mon", "Monday"), map:entry("Tue", "Tuesday"), map:entry("Wed", "Wednesday"), map:entry("Thu", "Thursday"), map:entry("Fri", "Friday"), map:entry("Sat", "Saturday") )) Unlike the map { ... } expression, this technique can be used to construct a map with a variable number of entries, for example: map:merge(for $b in //book return map:entry($b/isbn, $b))
Examples	map:entry("M", "Monday") creates map { "M": "Monday" }.

map:find

Signature	map:find( $input as item()*, $key as xs:anyAtomicType ) as array(*)
Summary	Returns all values of maps in the supplied $input with the specified $key. The found values will be returned in an array. Arbitrary input will be processed recursively as follows: In a sequence, each item will be processed in order. In an array, all array members will be processed as sequence. In a map, all entries whose keys match the specified key. Moreover, all values of the map will be processed as sequence.
Examples	map:find(map { 1:2 }, 1) returns [ 2 ]. map:find(map { 1: map { 2: map { 3: 4 } } }, 3) returns [ 4 ]. map:find((1, 'b', true#0), 1) returns an empty array.

map:for-each

Signature	map:for-each( $map as map(*), $action as function(xs:anyAtomicType, item()*) as item()* ) as item()*
Summary	Applies the specified $action to every key/value pair of the supplied $map and returns the results as a sequence.
Examples	The following query adds the keys and values of all map entries and returns (3,7): map:for-each( map { 1: 2, 3: 4 }, function($key, $value) { $key + $value } )

map:get

Signature	map:get( $map as map(*), $key as xs:anyAtomicType ) as item()*
Summary	Returns the value associated with a supplied key in a given map. This function attempts to find an entry within the $map that has a key equal to the supplied value of $key. If there is such an entry, the function returns the associated value; otherwise it returns an empty sequence. No error is raised if the map contains keys that are not comparable with the supplied $key. If the supplied key is xs:untypedAtomic, it is converted to xs:string. A return value of () from map:get could indicate that the key is present in the map with an associated value of (), or it could indicate that the key is not present in the map. The two cases can be distinguished by calling map:contains. Invoking the map as a function item has the same effect as calling get: that is, when $map is a map, the expression $map($K) is equivalent to get($map, $K). Similarly, the expression get(get(get($map, 'employee'), 'name'), 'first') can be written as $map('employee')('name')('first').
Examples	map:get($week, 4) returns "Thu". map:get($week, 9) returns (). (When the key is not present, the function returns an empty sequence.). map:get(map:entry(7,())), 7) returns (). (An empty sequence as the result can also signify that the key is present and the associated value is an empty sequence.).

map:keys

Signature	map:keys( $map as map(*) ) as xs:anyAtomicType*
Summary	Returns a sequence containing all the key values present in a map. The function takes the supplied $map and returns the keys that are present in the map as a sequence of atomic values. The order may differ from the order in which entries were inserted in the map.
Examples	map:keys(map { 1: "yes", 2: "no" }) returns (1,2).

map:merge

Signature	map:merge( $maps as map(*)*, $options as map(*) := map { } ) as map(*)
Summary	Constructs and returns a new map. The map is formed by combining the contents of the supplied $maps. The maps are combined as follows: There is one entry in the new map for each distinct key present in the union of the input maps. The $options argument defines how duplicate keys are handled. Currently, a single option duplicates exists, and its allowed values are use-first, use-last, combine and reject (default: use-first).
Examples	map:merge(()) creates an empty map. map:merge((map:entry(0, "no"), map:entry(1, "yes"))) creates map { 0: "no", 1: "yes" }. The following function adds a seventh entry to an existing map: map:merge(($week, map { 7: "---" })) In the following example, the values of all maps are combined, resulting in a map with a single key (map { "key": (1, 2, 3) }): map:merge( for $i in 1 to 3 return map { 'key': $i }, map { 'duplicates': 'combine' } )

map:put

Signature	map:put( $map as map(*), $key as xs:anyAtomicType, $value as item()* ) as map(*)
Summary	Creates a new map, containing the entries of the supplied $map and a new entry composed by $key and $value. The semantics of this function are equivalent to map:merge((map { $key, $value }, $map))

map:remove

Signature	map:remove( $map as map(*), $keys as xs:anyAtomicType* ) as map(*)
Summary	Constructs a new map by removing entries from an existing map. The entries in the new map correspond to the entries of $map, excluding entries supplied via $keys. No failure occurs if the input map contains no entry with the supplied keys; the input map is returned unchanged.
Examples	map:remove($week, 4) creates map { 0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 5: "Fri", 6: "Sat" }. map:remove($week, 23) creates map { 0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat" }.

map:size

Signature	map:size( $map as map(*) ) as xs:integer
Summary	Returns a the number of entries in the supplied map. The function takes the supplied $map and returns the number of entries that are present in the map.
Examples	map:size(map:merge(())) returns 0. map:size(map { "true": 1, "false": 0 }) returns 2.

Changelog

Version 8.6

• Added: map:find
• Updated: map:merge: Signature extended with options argument. By default, value of first key is now adopted (instead of last, as in previous versions).

Version 8.4

• Removed: map:serialize (use fn:serialize instead)

Version 8.0

• Added: map:for-each, map:merge, map:put
• Removed: support for collations (in accordance with the XQuery 3.1 spec).
• Removed: map:new (replaced with map:merge)
• Updated: aligned with latest specification: compare keys of type xs:untypedAtomic as xs:string instances, store xs:float or xs:double value NaN.
• Introduction on maps is now found in the article on XQuery 3.1.

Version 7.8

• Updated: map syntax map { 'key': 'value' }
• Added: map:serialize

Version 7.7.1

• Updated: alternative map syntax without map keyword and : as key/value delimiter (e.g.: { 'key': 'value' })