Difference between revisions of "Map Module"
m (Text replacement - "<syntaxhighlight lang="xquery">" to "<pre lang='xquery'>") |
|||
Line 8: | Line 8: | ||
Some examples use the ''map'' {{Code|$week}} defined as: | Some examples use the ''map'' {{Code|$week}} defined as: | ||
− | < | + | <pre lang='xquery'> |
declare variable $week := map { | declare variable $week := map { | ||
0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat" | 0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat" | ||
Line 48: | Line 48: | ||
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: | 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: | ||
− | < | + | <pre lang='xquery'> |
map:merge(( | map:merge(( | ||
map:entry("Sun", "Sunday"), | map:entry("Sun", "Sunday"), | ||
Line 61: | Line 61: | ||
Unlike the <code>map { ... }</code> expression, this technique can be used to construct a map with a variable number of entries, for example: | Unlike the <code>map { ... }</code> expression, this technique can be used to construct a map with a variable number of entries, for example: | ||
− | < | + | <pre lang='xquery'>map:merge(for $b in //book return map:entry($b/isbn, $b))</syntaxhighlight> |
|- valign="top" | |- valign="top" | ||
| '''Examples''' | | '''Examples''' | ||
Line 103: | Line 103: | ||
| '''Examples''' | | '''Examples''' | ||
|The following query adds the keys and values of all map entries and returns {{Code|(3,7)}}: | |The following query adds the keys and values of all map entries and returns {{Code|(3,7)}}: | ||
− | < | + | <pre lang='xquery'> |
map:for-each( | map:for-each( | ||
map { 1: 2, 3: 4 }, | map { 1: 2, 3: 4 }, | ||
Line 167: | Line 167: | ||
* {{Code|map:merge((map:entry(0, "no"), map:entry(1, "yes")))}} creates <code>map { 0: "no", 1: "yes" }</code>. | * {{Code|map:merge((map:entry(0, "no"), map:entry(1, "yes")))}} creates <code>map { 0: "no", 1: "yes" }</code>. | ||
* The following function adds a seventh entry to an existing map: | * The following function adds a seventh entry to an existing map: | ||
− | < | + | <pre lang='xquery'> |
map:merge(($week, map { 7: "---" })) | map:merge(($week, map { 7: "---" })) | ||
</syntaxhighlight> | </syntaxhighlight> | ||
* In the following example, the values of all maps are combined, resulting in a map with a single key (<code>map { "key": (1, 2, 3) }</code>): | * In the following example, the values of all maps are combined, resulting in a map with a single key (<code>map { "key": (1, 2, 3) }</code>): | ||
− | < | + | <pre lang='xquery'> |
map:merge( | map:merge( | ||
for $i in 1 to 3 return map { 'key': $i }, | for $i in 1 to 3 return map { 'key': $i }, |
Revision as of 18:31, 1 December 2023
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:
declare variable $week := map {
0: "Sun", 1: "Mon", 2: "Tue", 3: "Wed", 4: "Thu", 5: "Fri", 6: "Sat"
};
</syntaxhighlight>
==map:contains==
{| width='100%'
| width='120' | '''Signature'''
|<pre>map:contains(
$map as map(*),
$key as xs:anyAtomicType
) as xs:boolean
|- valign="top"
| 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.
|- valign="top"
| Examples
|
map:contains($week, 2)
returnstrue()
.map:contains($week, 9)
returnsfalse()
.map:contains(map {}, "xyz")
returnsfalse()
.map:contains(map { "xyz": 23 }, "xyz")
returnstrue()
.
|}
map:entry
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: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 <code>map { ... }</code> expression, this technique can be used to construct a map with a variable number of entries, for example:
<pre lang='xquery'>map:merge(for $b in //book return map:entry($b/isbn, $b))</syntaxhighlight>
|- valign="top"
| '''Examples'''
|{{Code|map:entry("M", "Monday")}} creates <code>map { "M": "Monday" }</code>.
|}
==map:find==
{| width='100%'
| width='120' | '''Signature'''
|<pre>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
Signature | map:for-each( $map as map(*), $action as function(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 | 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($key, $value) { $key + $value }
)
</syntaxhighlight>
|}
==map:get==
{| width='100%'
| width='120' | '''Signature'''
|<pre>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
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:merge
Signature | map:merge( $maps as map(*)*, $options as map(*) := 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 |
map:merge(($week, map { 7: "---" }))
</syntaxhighlight>
* In the following example, the values of all maps are combined, resulting in a map with a single key (<code>map { "key": (1, 2, 3) }</code>):
<pre lang='xquery'>
map:merge(
for $i in 1 to 3 return map { 'key': $i },
map { 'duplicates': 'combine' }
)
</syntaxhighlight>
|}
==map:put==
{| width='100%'
| width='120' | '''Signature'''
|<pre>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
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:size
Signature | 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' })