Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{{Mark|Updated with Version 8.6:}} Signature extended with options argument. By default, value of first key is now adopted.
no edit summary
This [[Module Library|XQuery Module]] contains functions for manipulating maps, which has been introduced with . [[XQuery 3.1#Maps|Maps]] have been introduced with [[XQuery 3.1]].
=Conventions=
Some examples use the ''map'' {{Code|$week}} defined as:
<pre classsyntaxhighlight lang="brush:xquery">declare variable $week as map(*) := map { 0: "SonntagSun", 1: "MontagMon", 2: "DienstagTue", 3: "MittwochWed", 4: "DonnerstagThu", 5: "FreitagFri", 6: "SamstagSat"
};
</presyntaxhighlight>
==map:contains==
The function {{Code|map:entry}} is intended primarily for use in conjunction with the function <code>[[#map:merge|map:merge]]</code>. For example, a map containing seven entries may be constructed like this:
<pre classsyntaxhighlight lang="brush:xquery">
map:merge((
map:entry("SuSun", "Sunday"), map:entry("MoMon", "Monday"), map:entry("TuTue", "Tuesday"), map:entry("WeWed", "Wednesday"), map:entry("ThThu", "Thursday"), map:entry("FrFri", "Friday"), map:entry("SaSat", "Saturday")
))
</presyntaxhighlight>
Unlike the <code>map { ... }</code> expression, this technique can be used to construct a map with a variable number of entries, for example:
<pre classsyntaxhighlight lang="brush:xquery">map:merge(for $b in //book return map:entry($b/isbn, $b))</presyntaxhighlight>
|-
| '''Examples'''
|{{Code|map:entry("M", "Monday")}} creates <code>map { "M": "Monday" }</code>.
|}
==map:find==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:find|$input as item()*, $key as xs:anyAtomicType|array(*)}}
|-
| '''Summary'''
| Returns all values of maps in the supplied {{Code|$input}} with the specified {{Code|$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'''
|
* <code>map:find(map { 1:2 }, 1)</code> returns <code>[ 2 ]</code>.
* <code>map:find(map { 1: map { 2: map { 3: 4 } } }, 3)</code> returns <code>[ 4 ]</code>.
* <code>map:find((1, 'b', true#0), 1)</code> returns an empty array.
|}
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:for-each|$map as map(*), $fun function as function(xs:anyAtomicType, item()*) as item()*|item()*}}
|-
| '''Summary'''
|Applies a the specified {{Code|$function }} to every entry key/value pair of the supplied {{Code|$map}} and returns the results as a sequence. The function supplied as {{Code|$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 {{Code|(3,7)}}:
<pre classsyntaxhighlight lang="brush:xquery">
map:for-each(
map { 1: 2, 3: 4 },
function($akey, $bvalue) { $a key + $b value }
)
</presyntaxhighlight>
|}
| '''Examples'''
|
* {{Code|map:get($week, 4)}} returns {{Code|"DonnerstagThu"}}.
* {{Code|map:get($week, 9)}} returns {{Code|()}}. ''(When the key is not present, the function returns an empty sequence.).''
* {{Code|map:get(map:entry(7,())), 7)}} returns {{Code|()}}. ''(An empty sequence as the result can also signify that the key is present and the associated value is an empty sequence.).''
==map:merge==
{| width='100%'
| Constructs and returns a new map. The ''map'' is formed by combining the contents of the supplied {{Code|$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 {{Code|$options}} argument defines how duplicate keys are handled. Currently, a single option {{Code|duplicates}} exists, and its allowed values are {{Code|use-first}}, {{Code|use-last}}, {{Code|use-combine}} and {{Code|reject}}(default: {{Code|use-first}}).
|-
| '''Examples'''
* {{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:
<pre classsyntaxhighlight lang="brush:xquery">map:merge(($week, map { 7: "Unbekannt---" }))</presyntaxhighlight>
* 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 classsyntaxhighlight lang="brush:xquery">
map:merge(
for $i in 1 to 3 return map { 'key': $i },
map { 'duplicates': 'combine' }
)
</presyntaxhighlight>
|}
|-
| '''Summary'''
| Creates a new ''map'', containing the entries of the supplied {{Code|$map}} and a new entry composed by {{Code|$key}} and {{Code|$value}}. The semantics of this function are equivalent to <code>map:merge(($map, map { $key, $value }, $map))</code>
|}
| '''Examples'''
|
* {{Code|map:remove($week, 4)}} creates <code>map { 0: "SonntagSun", 1: "MontagMon", 2: "DienstagTue", 3: "MittwochWed", 5: "FreitagFri", 6: "SamstagSat" }</code>.* {{Code|map:remove($week, 23)}} creates <code>map { 0: "SonntagSun", 1: "MontagMon", 2: "DienstagTue", 3: "MittwochWed", 4: "DonnerstagThu", 5: "FreitagFri", 6: "SamstagSat" }</code>.
|}
;Version 8.6
* Added: [[#map:find|map:find]]* Updated: [[#map:merge|map:merge]] signature : 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.0
* Added: <code>[[#map:for-each|map:for-each]]</code>, <code>[[#map:merge|map:merge]]</code>, <code>[[#map:put|map:put]]</code>
* Removed: support for collations (in accordance with the XQuery 3.1 spec).
* Removed: {{Code|map:new}} (replaced with {{Code|map:merge}})
