Map Module

This XQuery Module contains functions for manipulating maps, which will officially be 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

map:collation

Signatures	map:collation($map as map(*)) as xs:string
Summary	Returns the collation URI of the map supplied as $map.

map:contains

Signatures	map:contains($map as map(*), $key as xs:anyAtomicType) as xs:boolean
Summary	Returns true if the map supplied as $map contains an entry with a key equal to the supplied value of $key; otherwise it returns false. The equality comparison uses the map's collation; no error occurs 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. If the supplied key is the xs:float or xs:double value NaN, the function returns false.
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

Signatures	map:entry($key as xs:anyAtomicType, $value as item()*) as map(*)
Summary	Creates a new map containing a single entry. The collation of the new map is the default collation from the static context. The key of the entry in the new map is $key, and its associated value is $value. If the supplied key is xs:untypedAtomic, it is converted to xs:string. If the supplied key is the xs:float or xs:double value NaN, the supplied $map is returned unchanged. The function map:entry is intended primarily for use in conjunction with the function map:new. For example, a map containing seven entries may be constructed like this: map:new(( map:entry("Su", "Sunday"), map:entry("Mo", "Monday"), map:entry("Tu", "Tuesday"), map:entry("We", "Wednesday"), map:entry("Th", "Thursday"), map:entry("Fr", "Friday"), map:entry("Sa", "Saturday") )) Unlike the map{ ... } expression, this technique can be used to construct a map with a variable number of entries, for example: map:new(for $b in //book return map:entry($b/isbn, $b))
Examples	map:entry("M", "Monday") creates a map with the values { "M": "Monday" }.

map:get

Signatures	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 supplied as $map that has a key equal to the supplied value of $key. If there is such an entry, it returns the associated value; otherwise it returns an empty sequence. The equality comparison uses the map's collation; no error occurs 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. If the supplied key is the xs:float or xs:double value NaN, the function returns an empty sequence. 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 "Donnerstag". 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

Signatures	map:keys($map as map(*)) as xs:anyAtomicType*
Summary	Returns a sequence containing all the key values present in a map. The function takes any map as its $map argument and returns the keys that are present in the map as a sequence of atomic values, in implementation-dependent order.
Examples	map:keys(map{ 1: "yes", 2: "no" }) returns some permutation of (1,2) (the result is in implementation-dependent order).

map:new

Signatures	map:new() as map(*) map:new($maps as map(*)*) as map(*) map:new($maps as map(*)*, $coll as xs:string) as map(*)
Summary	Constructs and returns a new map. The zero-argument form of the function returns an empty map whose collation is the default collation in the static context. It is equivalent to calling the one-argument form of the function with an empty sequence as the value of the first argument. The one-argument form of the function returns a map that is formed by combining the contents of the maps supplied in the $maps argument. It is equivalent to calling the two-argument form of the function with the default collation from the static context as the second argument. The two-argument form of the function returns a map that is formed by combining the contents of the maps supplied in the $maps argument. The collation of the new map is the value of the $coll argument. The supplied maps are combined as follows: There is one entry in the new map for each distinct key value present in the union of the input maps, where keys are considered distinct according to the rules of the distinct-values function with $coll as the collation. The associated value for each such key is taken from the last map in the input sequence $maps that contains an entry with this key. If this map contains more than one entry with this key (which can happen if its collation is different from that of the new map) then it is implementation-dependent which of them is selected. 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	map:new() creates an empty map. map:new(()) creates an empty map. map:new((map:entry(0, "no"), map:entry(1, "yes"))) creates a map with the values { 0: "no", 1: "yes" }. map:new(($week, map{ 7: "Unbekannt" })) creates a map with the values { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" }. map:new(($week, map{ 6: "Sonnabend" })) creates a map with the values { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" }.

map:remove

Signatures	map:remove($map as map(*), $key as xs:anyAtomicType) as map(*)
Summary	Constructs a new map by removing an entry from an existing map. The collation of the new map is the same as the collation of the map supplied as $map. The entries in the new map correspond to the entries of $map, excluding any entry whose key is equal to $key. No failure occurs if the input map contains no entry with the supplied key; the input map is returned unchanged
Examples	map:remove($week, 4) creates a map with the values { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 5: "Freitag", 6: "Samstag" }. map:remove($week, 23) creates a map with the values { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag" }.

map:size

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

map:serialize

Signatures	map:serialize($map as map(*)) as xs:string
Summary	Returns a string representation of the supplied map. The purpose of this function is to get an insight into the structure of a map item. In most cases, it cannot be used for reconstructing the original map.
Examples	map:serialize({ 'A' : (.1, xs:date('2001-01-01')) }) returns { "A": (0.1, "2001-01-01") }.

Changelog

Version 8.0

• Introduction on maps moved to 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' })