Main Page » XQuery » Functions » Map Functions

Map Functions

This module provides functions for manipulating maps. It was introduced with XQuery 3.1 and 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

Signature	map:build( $input as item(), $keys as fn(item()) as xs:anyAtomicType := fn:identity#1, $value as fn(item()) as item()* := fn:identity#1, $options as map()? := {} ) as map()
Summary	Builds a map by evaluating `$keys` and `$value` for each item in the `$input` sequence. If the keys or value function is omitted, the item is adopted unchanged. The supported `$options` are the same as for `map:merge`.
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:build((5, 5), options := { 'duplicates': op('*') })` Result: `{ 5: 25 }`

map:build(
  $input    as item()*,
  $keys     as fn(item()) as xs:anyAtomicType*  := fn:identity#1,
  $value    as fn(item()) as item()*            := fn:identity#1,
  $options  as map(*)?                          := {}
) as map(*)

Summary Builds a map by evaluating $keys and $value for each item in the $input sequence. If the keys or value function is omitted, the item is adopted unchanged. The supported $options are the same as for map:merge.

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:build((5, 5), options := { 'duplicates': op('*') })

Result: { 5: 25 }

`map:contains`

Signature

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`.
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: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.

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

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

map:empty(
  $map  as map(*)
) as xs:boolean

Summary Returns 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()*
Summary	Returns a sequence with all key-value pairs of `$map`, each represented as singleton map.
Examples	`map:entries({})` Result: `()`

`map:entry`

Signature

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` 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: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 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

Signature	map:filter( $map as map(), $predicate as fn(xs:anyAtomicType, item()) as xs:boolean ) as map(*)
Summary	Returns 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:filter(
  $map        as map(*),
  $predicate  as fn(xs:anyAtomicType, item()*) as xs:boolean
) as map(*)

Summary Returns 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

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({ 1:2 }, 1)` Result: `[ 2 ]` `map:find({ 1: { 2: { 3: 4 } } }, 3)` Result: `[ 4 ]` `map:find((1, 'b', true#0), 1)` Result: `[]`

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({ 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()*
Summary	Applies 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

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

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:items`

Added: New function.

Signature	map:items( $map as map() ) as item()
Summary	Returns a sequence with all the values of `$map`.
Examples	`map:items({ 1: "yes", 2: "no" })` Result: `"yes", "no"`

`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({ 1: "yes", 2: "no" })` Result: `1, 2`

`map:keys-where`

Signature

Signature	map:keys-where( $map as map(), $predicate as fn(xs:anyAtomicType, item()) as xs:boolean ) as xs:anyAtomicType*
Summary	Returns 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:keys-where(
  $map        as map(*),
  $predicate  as fn(xs:anyAtomicType, item()*) as xs:boolean
) as xs:anyAtomicType*

Summary Returns 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(*)

Summary

Constructs 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: The following $options are available:

option	default	description
`duplicates`	`use-first`	Determines how the value of duplicate entries is created. The allowed values are `use-first`, `use-last`, `combine`, `use-any`, and `reject`, or a two-arity function.

Examples

map:merge(())

Result: {}

map:merge((map:entry(0, "no"), map:entry(1, "yes")))

Result: { 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 })

Result: { 'key': 1 }. By default, the value of the first map entry is adopted in the final map.

map:merge(
  for $i in 1 to 3 return { 'key': $i },
  { 'duplicates': 'combine' }
)

Result: { 'key': (1, 2, 3) }. All values are concatenated and returned in a single map entry.

map:merge(
  for $i in 1 to 3 return { 'key': $i },
  { 'duplicates': fn($v1, $v2) { $v1 * $v2 } }
)

Result: { 'key': 6 }. The value of the single map entry represents the product of all values.

`map:of-pairs`

Signature	map:of-pairs( $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 key-value pairs. The supported `$options` are the same as for `map:merge`.
Examples	`map:of-pairs({ 'key': 1, 'value': 2 })` Result: `{ 1: 2 }`

`map:pairs`

Signature

Signature	map:pairs( $map as map() ) as record(key, value)
Summary	Returns a sequence with all key-value pairs of `$map`, each represented as map with a `key` and a `value` entry.
Examples	`map:pairs({})` Result: `()` `map:pairs({ 1: 2 })` Result: `{ 'key': 1, 'value': 2 }`

map:pairs(
  $map  as map(*)
) as record(key, value)*

Summary Returns a sequence with all key-value pairs of $map, each represented as map with a key and a value entry.

Examples

map:pairs({})

Result: ()

map:pairs({ 1: 2 })

Result: { 'key': 1, 'value': 2 }

`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:remove`

Signature

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 `{ 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: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 { 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

Signature	map:size( $map as map(*) ) as xs:integer
Summary	Returns 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`

map:size(
  $map  as map(*)
) as xs:integer

Summary Returns 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 12.0

Added: map:items, map:of-pairs, map:pairs.
Updated: map:merge, map:build and map:of-pairs unified.

Version 11.0

Added: map:build, map:empty, map:entries, map:filter, map:keys-where.
Updated: Shorter map syntax { 'key': 'value' }

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