Difference between revisions of "Map Module"
m (Text replacement - "\[\[#(map:[^|]+)\|(map:[^|]+)\]\]" to "{{Function||$1}}") |
|||
Line 40: | Line 40: | ||
| '''Summary''' | | '''Summary''' | ||
| Creates a new ''map'' containing a single entry. The key of the entry in the new map is {{Code|$key}}, and its associated value is {{Code|$value}}. | | Creates a new ''map'' containing a single entry. The key of the entry in the new map is {{Code|$key}}, and its associated value is {{Code|$value}}. | ||
− | The function {{Code|map:entry}} is intended primarily for use in conjunction with the function <code> | + | The function {{Code|map:entry}} is intended primarily for use in conjunction with the function <code>{{Function||map:merge}}</code>. For example, a map containing seven entries may be constructed like this: |
<syntaxhighlight lang="xquery"> | <syntaxhighlight lang="xquery"> | ||
Line 203: | Line 203: | ||
;Version 8.6 | ;Version 8.6 | ||
− | * Added: | + | * Added: {{Function||map:find}} |
− | * Updated: | + | * Updated: {{Function||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 | ;Version 8.4 | ||
Line 210: | Line 210: | ||
;Version 8.0 | ;Version 8.0 | ||
− | * Added: | + | * Added: {{Function||map:for-each}}, {{Function||map:merge}}, {{Function||map:put}} |
* Removed: support for collations (in accordance with the XQuery 3.1 spec). | * Removed: support for collations (in accordance with the XQuery 3.1 spec). | ||
* Removed: {{Code|map:new}} (replaced with {{Code|map:merge}}) | * Removed: {{Code|map:new}} (replaced with {{Code|map:merge}}) | ||
Line 218: | Line 218: | ||
;Version 7.8 | ;Version 7.8 | ||
* Updated: map syntax <code>map { 'key': 'value' }</code> | * Updated: map syntax <code>map { 'key': 'value' }</code> | ||
− | * Added: | + | * Added: {{Function||map:serialize}} |
;Version 7.7.1 | ;Version 7.7.1 | ||
* Updated: alternative map syntax without {{Code|map}} keyword and {{Code|:}} as key/value delimiter (e.g.: <code>{ 'key': 'value' })</code> | * Updated: alternative map syntax without {{Code|map}} keyword and {{Code|:}} as key/value delimiter (e.g.: <code>{ 'key': 'value' })</code> |
Revision as of 19:48, 18 July 2022
This XQuery Module contains functions for manipulating maps. Maps have been introduced with XQuery 3.1.
Contents
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:
<syntaxhighlight lang="xquery">
declare variable $week := map {
0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat"
}; </syntaxhighlight>
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 |
Examples |
|
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 <syntaxhighlight lang="xquery"> 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") )) </syntaxhighlight> Unlike the |
Examples | map:entry("M", "Monday") creates map { "M": "Monday" } .
|
map:find
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:
|
Examples |
|
map:for-each
Signatures | map:for-each($map as map(*), $function as function(xs:anyAtomicType, item()*) as item()*) as item()*
|
Summary | Applies the specified $function 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) :
<syntaxhighlight lang="xquery"> map:for-each( map { 1: 2, 3: 4 }, function($key, $value) { $key + $value } ) </syntaxhighlight> |
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 |
Examples |
|
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:merge
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:
|
Examples |
<syntaxhighlight lang="xquery"> map:merge(($week, map { 7: "---" })) </syntaxhighlight>
<syntaxhighlight lang="xquery"> map:merge( for $i in 1 to 3 return map { 'key': $i }, map { 'duplicates': 'combine' } ) </syntaxhighlight> |
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 { $key, $value }, $map))
|
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: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 |
|
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 withmap:merge
) - Updated: aligned with latest specification: compare keys of type
xs:untypedAtomic
asxs:string
instances, storexs:float
orxs:double
valueNaN
. - 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' })