Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
{| width='100%';Version 8.6| width='120' | '''Signatures'''|{{Func|* Added: [[#map:serializefind|$input as map(:find]]*)|xsUpdated:string}}<br/>|-| '''Summary'''| This function is specific to BaseX. It returns a string representation of the supplied [[#map. The purpose of this function is to get an insight into the structure of a map item; it cannot necessarily be used for reconstructing the original map.|-| '''Examples''':merge|* <code>map:serialize(map { 'A'merge]]: (Signature extended with options argument.1By default, xs:datevalue of first key is now adopted ('2001-01-01')) })</code> returns <code>{ "A": (0.1instead of last, "2001-01-01"as in previous versions) }</code>.|} [[Category:XQuery]]
=Changelog=;Version 8.4* Removed: map:serialize (use fn:serialize instead)
[[Category:XQuery]]
no edit summary
This [[Module Library|XQuery Module]] contains functions for manipulating maps, which will officially be introduced with . [[XQuery 3.1#Maps|Maps]] have been introduced with [[XQuery 3.1]].<br/>'''Please note''' that the functions are subject to change until the specification has reached its final stage.
=Conventions=
All functions in this module are assigned to the {{Code|<code><nowiki>http://www.w3.org/2005/xpath-functions/map}} </nowiki></code> namespace, which is statically bound to the {{Code|map}} prefix.<br/>
=Functions=
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==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:contains|$input map as map(*), $key as xs:anyAtomicType|xs:boolean}}
|-
| '''Summary'''
| Returns true if the ''map'' supplied as {{Code|$inputmap}} contains an entry with a key equal to the supplied value of {{Code|$key}}; otherwise it returns false. No error is raised if the map contains keys that are not comparable with the supplied {{Code|$key}}.
If the supplied key is {{Code|xs:untypedAtomic}}, it is compared as an instance of {{Code|xs:string}}. If the supplied key is the {{Code|xs:float}} or {{Code|xs:double}} value {{Code|NaN}}, the function returns true if there is an entry whose key is {{Code|NaN}}, or false otherwise.
|-
==map:entry==
{| width='100%'
| width='120' | '''Signatures'''
|-
| '''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}}. If the supplied key is {{Code|xs:untypedAtomic}}, it is compared as an instance of {{Code|xs:string}}. If the supplied key is the {{Code|xs:float}} or {{Code|xs:double}} value {{Code|NaN}}, the function returns the value in the entry whose key is {{Code|NaN}}, or the empty sequence otherwise.
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|$input map as map(*), $fun function as function(xs:anyAtomicType, item()*) as item()*|item()*}}
|-
| '''Summary'''
|Applies a function to every entry of the map specified {{Code|$inputfunction}} and returns to every key/value pair of the results as a sequence. The function supplied as {{Code|$funmap}} takes two arguments. It is called supplying the key of the map entry as the first argument, and returns the associated value results as the second argumenta sequence.
|-
| '''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>
|}
==map:get==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:get|$input map as map(*), $key as xs:anyAtomicType|item()*}}
|-
| '''Summary'''
|Returns the value associated with a supplied key in a given map. This function attempts to find an entry within the ''map'' supplied as {{Code|$inputmap}} that has a key equal to the supplied value of {{Code|$key}}. If there is such an entry, it 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 {{Code|$key}}. If the supplied key is {{Code|xs:untypedAtomic}}, it is converted to {{Code|xs:string}}. If the supplied key is the {{Code|xs:float}} or {{Code|xs:double}} value {{Code|NaN}}, the function returns an empty sequence.
A return value of {{Code|()}} from {{Code|map:get}} could indicate that the key is present in the map with an associated value of {{Code|()}}, or it could indicate that the key is not present in the map. The two cases can be distinguished by calling {{Code|map:contains}}.
Invoking the ''map'' as a function item has the same effect as calling {{Code|get}}: that is, when {{Code|$inputmap}} is a map, the expression {{Code|$inputmap($K)}} is equivalent to {{Code|get($inputmap, $K)}}. Similarly, the expression {{Code|get(get(get($inputmap, 'employee'), 'name'), 'first')}} can be written as {{Code|$inputmap('employee')('name')('first')}}.
|-
| '''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:keys==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:keys|$input map as map(*)|xs:anyAtomicType*}}
|-
| '''Summary'''
|Returns a sequence containing all the key values present in a map. The function takes any ''map'' as its the supplied {{Code|$inputmap}} argument 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'''
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:merge|$input maps as map(*)*|map(*)}}<br/>{{Func|map:merge|$maps as map(*)*, $options as map(*)|map(*)}}<br/>
|-
| '''Summary'''
| Constructs and returns a new map. The ''map'' is formed by combining the contents of the maps supplied in the {{Code|$inputmaps}} argument. The maps are combined as follows: # There is one entry in the new map for each distinct key value 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, where keys and its allowed values are considered distinct according to the rules of the {{Code|distinctuse-valuesfirst}} function.# The associated value for each such key is taken from the , {{Code|use-last map in the input sequence }}, {{Code|$inputcombine}} that contains an entry with this key. There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example and {{Code|mapreject}} (xsdefault:integer, xs:string){{Code|use-first}}) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.
|-
| '''Examples'''
* {{Code|map:merge(())}} creates an empty map.
* {{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:<codesyntaxhighlight lang="xquery">map:merge(($week, map { 7: "Unbekannt---" }))</codesyntaxhighlight> creates * In the following example, the values of all maps are combined, resulting in a map with a single key (<code>map { 0: "Sonntagkey", : (1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" ) }</code>.):* <codesyntaxhighlight lang="xquery">map:merge(( for $week, i in 1 to 3 return map { 6'key': "Sonnabend" $i }))</code> creates <code>, map { 0'duplicates': "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" 'combine' })</codesyntaxhighlight>.
|}
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:put|$input map as map(*), $key as xs:anyAtomicType, $value as item()*|map(*)}}
|-
| '''Summary'''
| Creates a new ''map'', containing the entries of the supplied {{Code|$inputmap}} argument and a new entry composed by {{Code|$key}} and {{Code|$value}}. The semantics of this function are equivalent to <code>map:merge(($input, map { $key, $value }, $map))</code>
|}
==map:remove==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:remove|$input map as map(*), $key keys as xs:anyAtomicType*|map(*)}}<br/>
|-
| '''Summary'''
| Constructs a new map by removing an entry entries from an existing map. The entries in the new map correspond to the entries of {{Code|$inputmap}}, excluding any entry whose key is equal to entries supplied via {{Code|$keykeys}}.No failure occurs if the input map contains no entry with the supplied keykeys; the input map is returned unchanged.
|-
| '''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>.
|}
==map:size==
{| width='100%'
| width='120' | '''Signatures'''
|{{Func|map:size|$input map as map(*)|xs:integer}}<br/>
|-
| '''Summary'''
| Returns a the number of entries in the supplied map. The function takes any ''map'' as its the supplied {{Code|$inputmap}} argument and returns the number of entries that are present in the map.
|-
| '''Examples'''
|}
==map:serialize=Changelog=
;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}})
;Version 7.8
* Updated: map syntax <code>map { 'key': 'value' }</code>
* Added: [[#map:serialize|map:serialize]]
;Version 7.7.1
* Updated: alternative map syntax without {{Code|map}} keyword and {{Code|:}} as key/value delimiter (e.g.: <code>{ 'key': 'value' })</code>
