Main Page » XQuery » Functions » Map Functions

Map Functions

This module provides functions for manipulating maps. It was introduced with XQuery 3.1 and will be extended with XQuery 4.0. All functions are described in detail in the XQuery Functions and Operators Specification.

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 := {
  0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat"
};

map:build

Signature
map:build(
  $input    as item()*,
  $key      as fn(item()) as xs:anyAtomicType*  := fn:identity#1,
  $value    as fn(item()) as item()*            := fn:identity#1,
  $combine  as fn(item()*, item()*) as item()*  := fn:op(',')
) as map(*)
SummaryBuilds a map by evaluating $key and $value for each item in the $input sequence. If the key or value function is omitted, the item is adopted unchanged.
Examples
map:build(1 to 3)
Result: { 1: 1, 2: 2, 3: 3 }
map:build(1 to 3, value := fn { . * 10 })
Result: { 1: 10, 2: 20, 3: 30 }
map:build(-1 to 1, abs#1, string#1, fn($a, $b) { string-join(($a, $b), ',') })
Result: { 0: '0', 1: '-1,1' }

map:contains

Signature
map:contains(
  $map  as map(*),
  $key  as xs:anyAtomicType
) as xs:boolean
SummaryReturns 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.
Examples
map:contains($week, 2)
Result: true()
map:contains($week, 9)
Result: false()
map:contains({}, "xyz")
Result: false()
map:contains({ "xyz": 23 }, "xyz")
Result: true()

map:empty

Signature
map:empty(
  $map  as map(*)
) as xs:boolean
SummaryReturns true if $map contains no entries.
Examples
map:empty({ 1: 'x' })
Result: false()
map:empty({})
Result: true()

map:entries

Signature
map:entries(
  $map  as map(*)
) as map(*)*
SummaryReturns a sequence with all key-value pairs of $map, each represented as singleton map.
Examples
map:entries({})
Result: ()

map:entry

Signature
map:entry(
  $key    as xs:anyAtomicType,
  $value  as item()*
) as map(*)
SummaryCreates 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 can be used 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 { ... } 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 { "M": "Monday" }.

map:filter

Signature
map:filter(
  $map        as map(*),
  $predicate  as fn(xs:anyAtomicType, item()*) as xs:boolean
) as map(*)
SummaryReturns a new map with those members of $map for which $predicate returns true.
Examples
map:filter({ 0: 0, 2: 3210, 4: 4, 8: 9876 }, op('='))
Result: { 0: 0, 4: 4 }
map:filter(
  { 1: 'I', 2: 'II', 3: 'III', 4: 'IV', 5: 'V' },
  fn($key, $value) { string-length($value) = 1 }
)
Result: { 1: 'I', 5: 'V' }

map:find

Signature
map:find(
  $input  as item()*,
  $key    as xs:anyAtomicType
) as array(*)
SummaryReturns 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({ 1:2 }, 1)
Result: [ 2 ]
map:find({ 1: { 2: { 3: 4 } } }, 3)
Result: [ 4 ]
map:find((1, 'b', true#0), 1)
Result: []

map:for-each

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

map:get

Signature
map:get(
  $map  as map(*),
  $key  as xs:anyAtomicType
) as item()*
SummaryReturns 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.

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 map:get($map, $K).

Examples
map:get($week, 4)
Result: "Thu"
map:get($week, 9)
Result: ()
map:get({ 7: () }, 7)
Result: ()

map:keys

Signature
map:keys(
  $map  as map(*)
) as xs:anyAtomicType*
SummaryReturns 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({ 1: "yes", 2: "no" })
Result: (1,2)

map:keys-where

Signature
map:keys-where(
  $map        as map(*),
  $predicate  as fn(xs:anyAtomicType, item()*) as xs:boolean
) as xs:anyAtomicType*
SummaryReturns the keys of $map whose entries match the $predicate function.
Examples
map:keys-where(
  { 1: 'I', 2: 'II', 3: 'III', 4: 'IV', 5: 'V' },
  fn($key, $value) { string-length($value) = 1 }
)
Result: 1, 5

map:merge

Signature
map:merge(
  $maps     as map(*)*,
  $options  as map(*)   := { }
) as map(*)
SummaryConstructs and returns a new map. The map is formed by combining the contents of the supplied $maps, and the new map will have one entry for each distinct key present in the union of the input maps. The following $options are available:
optiondefaultdescription
duplicatesuse-first Determine how duplicate keys are handled.
The allowed values are use-first, use-last, combine, and reject.
Examples
map:merge(())
Creates an empty map.
map:merge((map:entry(0, "no"), map:entry(1, "yes")))
Creates { 0: "no", 1: "yes" }.
map:merge(($week, { 7: "---" }))
Adds a seventh entry to an existing map.
map:merge(
  for $i in 1 to 3 return { 'key': $i },
  { 'duplicates': 'combine' }
)
The values of all maps are combined, resulting in a map with a single key ({ "key": (1, 2, 3) }).

map:put

Signature
map:put(
  $map    as map(*),
  $key    as xs:anyAtomicType,
  $value  as item()*
) as map(*)
SummaryCreates 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(({ $key, $value }, $map))

map:remove

Signature
map:remove(
  $map   as map(*),
  $keys  as xs:anyAtomicType*
) as map(*)
SummaryConstructs 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 { 0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 5: "Fri", 6: "Sat" }.
map:remove($week, 23)
Creates { 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
SummaryReturns 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(()))
Result: 0
map:size({ "true": 1, "false": 0 })
Result: 2

Changelog

Version 11.0Version 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.4Version 8.0
  • Added: map:for-each, map:merge, map:put
  • Updated: aligned with latest specification: compare keys of type xs:untypedAtomic as xs:string instances, store xs:float or xs:double value NaN.
  • Removed: support for collations (in accordance with the XQuery 3.1 spec).
  • Removed: map:new (replaced with map:merge)
  • Introduction on maps is now found in the article on [XQuery 3.1](?#Maps).:
    • Introduction on maps is now found in the article on XQuery 3.1.
Version 7.8
  • Added: map:serialize
  • Updated: map syntax map { 'key': 'value' }
Version 7.7.1
  • Updated: alternative map syntax without map keyword and : as key/value delimiter (e.g.: { 'key': 'value' })

⚡Generated with XQuery