Changes

This module contains [[Querying#FunctionsModule Library|XQuery FunctionsModule]] contains functions for manipulating maps. All functions are preceded by the <code>map:</code> prefix, which is linked to the <code>http://www.w3.org/2005/xpath-functions/map</code> namespace. The following documentation is derived from an [http://www.w3.org/TR/xpath-functions-30/ [XQuery 3.0 Functions and Operators1#Maps|Maps] working draft proposal written by ] have been introduced with [http://en[XQuery 3.wikipedia.org/wiki/Michael_Kay_(software_engineer) Michael H. Kay1]].

The function call All functions in this module are assigned to the <code>[[#map<nowiki>http:get|//www.w3.org/2005/xpath-functions/map:get($map, $key)]]</nowiki></code> can be used namespace, which is statically bound to retrieve the value associated with a given key{{Code|map}} prefix.<br/>

Some examples use the ''map'' {{Code|$week}} defined as:<pre classlang="brush:'xquery"'>let declare variable $map week := map { 'foo' 0: "Sun", 1: "Mon", 2:= 42"Tue", 'bar' 3:= 'baz'"Wed", 123 4:= 456 }return fn"Thu", 5:map($map"Fri", map6:keys($map))"Sat"};

Like all other values{| width='100%'| width='120' | '''Signature'''|<pre>map:contains( $map as map(*), $key as xs:anyAtomicType) as xs:boolean</pre>|- valign="top"| '''Summary'maps'' | Returns true if the supplied {{Code|$map}} 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 immutablenot comparable with the supplied {{Code|$key}}. For exampleIf 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.|- valign="top"| '''Examples'''| * {{Code|map:contains($week, 2)}} returns {{Code|true()}}.* {{Code|map:contains($week, 9)}} returns {{Code|false()}}.* <code>map:removecontains(map {}, "xyz")</code> function creates a new returns {{Code|false()}}.* <code>map by removing an entry from an existing :contains(map{ "xyz": 23 }, but the existing map is not changed by the operation"xyz")</code> returns {{Code|true()}}.|}

Like sequences, ''maps'' have no identity. It is meaningful to compare the contents of two maps, but there is no way of asking whether they are "the same ==map": two maps with the same content are indistinguishable.entry==

Because {| width='100%'| width='120' | '''Signature'''|<pre>map:entry( $key as xs:anyAtomicType, $value as item()*) as map(*)</pre>|- valign="top"| '''Summary'''| Creates a new ''map is '' containing a function item, functions that apply to functions also apply to mapssingle entry. A The key of the entry in the new map is an anonymous {{Code|$key}}, and its associated value is {{Code|$value}}.The function, so <code>fn{{Code|map:entry}} is intended primarily for use in conjunction with the function-name</code> returns the empty sequence; <code>fn{{Function||map:function-arity</code> always returns <code>1merge}}</code>.For example, a map containing seven entries may be constructed like this:

Maps may be compared using the <codepre lang='xquery'>fnmap:deep-equal</code> function. The semantics for this function are extended so that when two items are comparedmerge(( map:entry("Sun", at any level of recursion"Sunday"), the items compare equal if they are both maps map:entry("Mon", if both use the same collation, if both contain the same set of keys (compared using the <code>eq</code> operator"Monday"), without regard to ordering, and if for each key that is present in both maps, the associated values are deep-equal. When comparing maps, the maps' collation is used rather than the collation supplied as an argument to the <code>fn:deep-equal</code> function. There is no operation to atomize a map or convert it to a string. The following XQuery snippet shows how the contents of a map can be serialized: <pre class=entry("Tue", "brush:xqueryTuesday">),let $ map := map { 1:='a'entry("Wed", "Wednesday"), 2:='b' }return string-join( for $m in map:keysentry($map"Thu", "Thursday"), return concatmap:entry($m"Fri", ':='"Friday"), $ map:entry($m"Sat", "Saturday")), ', ')

Some examples use Unlike the ''map'' <code>$weekmap { ... }</code> defined asexpression, this technique can be used to construct a map with a variable number of entries, for example:<pre classlang="brush:'xquery"'>declare variable $week as map:merge(*) := for $b in //book return map { 0:="Sonntag"entry($b/isbn,$b))</pre> 1:|- valign="Montagtop", 2:="Dienstag",| '''Examples''' 3|{{Code|map:=entry("MittwochM", 4:="DonnerstagMonday", 5:=)}} creates <code>map { "FreitagM", 6:="SamstagMonday"}</code>.|};

==map:collation=={|| width='90' valign='top' | '''Signatures'''|<code><strong>map:collation</strong>($map as map(*)) as xs:string</code>|-| valign='top' | '''Summary'''| Returns the collation URI of the ''map'100%' supplied as <code>$map</code>.|} ==map:contains=={|| width='90' valign='top120' | '''SignaturesSignature'''|<code><strongpre>map:contains</strong>find( $map input as mapitem()*), $key as itemxs:anyAtomicType) as array(*)) as xs:boolean</codepre>|-| valign='"top' "| '''Summary'''| Returns true if all values of maps in the ''map'' supplied as <code>{{Code|$map</code> contains an entry input}} with a key equal to the supplied value of <code>specified {{Code|$key</code>; otherwise it returns false}}. The equality comparison uses the map's collation; no error occurs if the map contains keys that are not comparable with the supplied <code>$key</code>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.If the supplied key is <code>xs:untypedAtomic</code>* In an array, it is converted to <code>xs:string</code>all array members will be processed as sequence. If * In a map, all entries whose keys match the supplied specified key is the <code>xs:float</code> or <code>xs:double</code> value <code>NaN</code>. Moreover, all values of the function returns falsemap will be processed as sequence.|-| valign='"top' "| '''Examples'''

* <code>map:containsfind($weekmap { 1:2 }, 21)</code> returns <code>true()[ 2 ]</code>.* <code>map:containsfind($week, 9)</code> returns <code>false()</code>.* <code>map{ 1: map { 2:contains(map{3: 4 } } }, "xyz"3)</code> returns <code>false()[ 4 ]</code>.* <code>map:containsfind((map{ "xyz":=23 }1, 'b', true#0), "xyz"1)</code> returns <code>true()</code>an empty array.

==map:entry=for-each={|| width='90' valign='top' | '''Signatures'''|<code><strong>map:entry</strong>($key as item(), $value as item()*) as map(*)</code>|-| valign='top' | '''Summary'''| Creates a new ''map'' containing a single entry. The collation of the new map is the default collation from the static context. The key of the entry in the new map is <code>$key</code>, and its associated value is <code>$value</code>. If the supplied key is <code>xs:untypedAtomic</code>, it is converted to <code>xs:string</code>. If the supplied key is the <code>xs:float</code> or <code>xs:double</code> value <code>NaN</code>, the supplied <code>$map</code> is returned unchanged.The function <code>map:entry</code> is intended primarily for use in conjunction with the function <code>[[#map:new|map:new]]</code>. For example, a map containing seven entries may be constructed like this:

{| width='100%'| width='120' | '''Signature'''|<pre class="brush:xquery">map:new(for-each( $map as map:entry("Su", "Sunday"*), map$action as function(xs:entryanyAtomicType, item()*) as item("Mo", "Monday"),* map:entry) as item()*</pre>|- valign="Tutop", | '''Summary'''|Applies the specified {{Code|$action}} to every key/value pair of the supplied {{Code|$map}} and returns the results as a sequence.|- valign="Tuesdaytop"), | '''Examples'''|The following query adds the keys and values of all map:entryentries and returns {{Code|("We"3, "Wednesday"7),}}:<pre lang='xquery'> map:entryfor-each("Th", "Thursday"), map{ 1:entry("Fr"2, "Friday")3: 4 }, map:entryfunction("Sa"$key, "Saturday"$value){ $key + $value }))

 {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''|<code><strongpre>map:get</strong>( $map as map(*), $key as item()xs:anyAtomicType) as item()*</codepre>|-| valign='"top' "| '''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>{{Code|$map</code> }} that has a key equal to the supplied value of <code>{{Code|$key</code>}}. If there is such an entry, it the function returns the associated value; otherwise it returns an empty sequence. The equality comparison uses the map's collation; no No error occurs is raised if the map contains keys that are not comparable with the supplied <code>{{Code|$key</code>}}. If the supplied key is <code>{{Code|xs:untypedAtomic</code>}}, it is converted to <code>{{Code|xs:string</code>. If the supplied key is the <code>xs:float</code> or <code>xs:double</code> value <code>NaN</code>, the function returns an empty sequence}}.A return value of <code>{{Code|()</code> }} from <code>{{Code|map:get</code> }} could indicate that the key is present in the map with an associated value of <code>{{Code|()</code>}}, or it could indicate that the key is not present in the map. The two cases can be distinguished by calling <code>{{Code|map:contains</code>}}.Invoking the ''map'' as a function item has the same effect as calling <code>{{Code|get</code>}}: that is, when <code>{{Code|$map</code> }} is a map, the expression <code>{{Code|$map($K)</code> }} is equivalent to <code>{{Code|get($map, $K)</code>}}. Similarly, the expression <code>{{Code|get(get(get($map, 'employee'), 'name'), 'first')</code> }} can be written as <code>{{Code|$map('employee')('name')('first')</code>}}.|-| valign='"top' "| '''Examples'''

* <code>{{Code|map:get($week, 4)</code> }} returns <code>{{Code|"DonnerstagThu"</code>}}.* <code>{{Code|map:get($week, 9)</code> }} returns <code>{{Code|()</code>}}. ''(When the key is not present, the function returns an empty sequence.).''* <code>{{Code|map:get(map:entry(7,())), 7)</code> }} returns <code>{{Code|()</code>}}. ''(An empty sequence as the result can also signify that the key is present and the associated value is an empty sequence.).''

 {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''|<code><strongpre>map:keys</strong>( $map as map(*)) as xs:anyAtomicType*</codepre>|-| valign='"top' "| '''Summary'''|Returns a sequence containing all the key values present in a map. The function takes any ''map'' as its <code>the supplied {{Code|$map</code> 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 implementation-dependent orderthe map.|-| valign='"top' "| '''Examples'''

* <code>map:keys(map{ 1:="yes", 2:="no" })</code> returns some permutation of <code>{{Code|(1,2)</code> ''(the result is in implementation-dependent order)}}.''

==map:newmerge== {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''|<code><strongpre>map:new</strong>() as map(*)</code><br/><code><strong>map:new</strong>merge( $maps as map(*)*) , $options as map(*)</code><br/><code><strong>map :new</strong>($maps as = map(*)*, $coll as xs:string{ }) as map(*)</codepre>|-| valign='"top' "| '''Summary'''| Constructs and returns a new map. The zero-argument form of the function returns an empty ''map'' whose collation is formed by combining the default collation in contents of the static contextsupplied {{Code|$maps}}. It The maps are combined as follows:# There is equivalent to calling the one-argument form of entry in the function with an empty sequence as new map for each distinct key present in the value union of the first argumentinput maps.# The one-{{Code|$options}} argument form of the function returns 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|combine}} and {{Code|reject}} (default: {{Code|use-first}}).|- valign="top"| ''map'Examples''' that is formed by combining the contents of the maps supplied in the |* {{Code|map:merge(())}} creates an empty map.* {{Code|map:merge((map:entry(0, "no"), map:entry(1, "yes")))}} creates <code>$mapsmap { 0: "no", 1: "yes" }</code> argument. It is equivalent to calling the two-argument form of the function with the default collation from the static context as the second argument.* The two-argument form of the following function returns adds a seventh entry to an existing map:<pre lang='xquery'>map:merge(($week, map'' that is formed by combining { 7: "---" }))</pre>* In the following example, the contents values of the all maps supplied are combined, resulting in the a map with a single key (<code>$mapsmap { "key": (1, 2, 3) }</code> argument. The collation of the new map is the value of the ):<codepre lang='xquery'>map:merge( for $i in 1 to 3 return map { 'key': $colli }, map { 'duplicates': 'combine' })</codepre> argument. The supplied 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, where keys are considered distinct according to the rules of the <code>distinct-values</code> function with <code>$coll</code> as the collation.# The associated value for each such key is taken from the last map in the input sequence <code>$maps</code> that contains an entry with this key. If this map contains more than one entry with this key (which can happen if its collation is different from that of the new map) then it is ''implementation-dependent'' which of them is selected.:put==

There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example <code>map(xs:integer, xs:string)</code>) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps.{|-width='100%'| valignwidth='top120' | '''ExamplesSignature'''|* <codepre>map:newput()</code> creates an empty $map.* <code> as map:new((*))</code> creates an empty map.,* <code>map $key as xs:newanyAtomicType, $value as item(map:entry(0, "no"), *) as map:entry(1, "yes")*)</codepre> creates a map with the values <code>{ 0:|- valign="notop", 1:="yes" }</code>.* <code>map:| '''Summary'''| Creates a new(''map:entry(0'', "no"), map:entry(1, "yes"))</code> creates a map with containing the entries of the values <code>supplied {{ 0:="no", 1:="yes" Code|$map}}</code>.* <code>map:and a new((entry composed by {{Code|$week, mapkey}} and {{ 7:="Unbekannt" Code|$value}))</code> creates a map with the values <code>{ 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag", 7:="Unbekannt" }</code>.* The semantics of this function are equivalent to <code>map:newmerge((map { $weekkey, $value }, $map{ 6:="Sonnabend" }))</code> creates a map with the values <code>{ 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Sonnabend" }</code>.

 {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''|<code><strongpre>map:remove</strong>( $map as map(*), $key keys as item()xs:anyAtomicType*) as map(*)</code><br/pre>|-| valign='"top' "| '''Summary'''| Constructs a new map by removing an entry entries from an existing map. The collation of the new map is the same as the collation of the map supplied as <code>$map</code>. The entries in the new map correspond to the entries of <code>{{Code|$map</code>}}, excluding any entry whose key is equal to <code>entries supplied via {{Code|$key</code>keys}}.No failure occurs if the input map contains no entry with the supplied keykeys; the input map is returned unchanged.|-| valign='"top' "| '''Examples'''

* <code>{{Code|map:remove($week, 4)}} creates </code> creates a map with the values <code>{ 0:="SonntagSun", 1:="MontagMon", 2:="DienstagTue", 3:="MittwochWed", 5:="FreitagFri", 6:="SamstagSat" }</code>.* <code>{{Code|map:remove($week, 23)}} creates </code> creates a map with the values <code>{ 0:="SonntagSun", 1:="MontagMon", 2:="DienstagTue", 3:="MittwochWed", 4:="DonnerstagThu", 5:="FreitagFri", 6:="SamstagSat" }</code>.

 {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''|<code><strongpre>map:size</strong>( $map as map(*)) as xs:integer</code><br/pre>|-| valign='"top' "| '''Summary'''| Returns a the number of entries in the supplied map. The function takes any ''map'' as its <code>the supplied {{Code|$map</code> argument }} and returns the number of entries that are present in the map.|-| valign='"top' "| '''Examples'''

* <code>{{Code|map:size(map:newmerge(()))</code> }} returns <code>{{Code|0</code>}}.* <code>map:size(map{ "true":=1, "false":=0 })</code> returns <code>{{Code|2</code>}}.

=Changelog= ;Version 8.6* Added: {{Function||map:find}}* 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* Removed: map:serialize (use fn:serialize instead) ;Version 8.0* Added: {{Function||map:for-each}}, {{Function||map:merge}}, {{Function||map:put}}* Removed: support for collations (in accordance with the XQuery 3.1 spec).* Removed: {{Code|map:new}} (replaced with {{Code|map:merge}})* Updated: aligned with latest specification: compare keys of type {{Code|xs:untypedAtomic}} as {{Code|xs:string}} instances, store {{Code|xs:float}} or {{Code|xs:double}} value {{Code|NaN}}.* Introduction on maps is now found in the article on [[Category:XQuery3.1#Maps|XQuery 3.1]]. ;Version 7.8* Updated: map syntax <code>map { 'key': 'value' }</code>* Added: {{Function||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>