This XQuery Module contains functions for manipulating maps, which has 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
Signatures
|
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
Signatures
|
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
Template:Mark
Signatures
|
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:for-each
Signatures
|
map:for-each($map as map(*), $fun as function(xs:anyAtomicType, item()*) as item()*) as item()*
|
Summary
|
Applies a function to every entry of the supplied $map and returns the results as a sequence. The function supplied as $fun takes two arguments. It is called supplying the key of the map entry as the first argument, and the associated value as the second argument.
|
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($a, $b) { $a + $b }
)
|
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 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
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 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
Template:Mark Signature extended with options argument. By default, value of first key is now adopted.
Signatures
|
map:merge($maps as map(*)*) as map(*)
map:merge($maps as map(*)*, $options as 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 , use-combine and reject .
|
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
Signatures
|
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, map { $key, $value }))
|
map:remove
Signatures
|
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
Signatures
|
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
- 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
- Version 7.7.1
- Updated: alternative map syntax without
map
keyword and :
as key/value delimiter (e.g.: { 'key': 'value' })