Changes

<p>This module contains [[Querying#FunctionsModule Library|XQuery FunctionsModule]] contains functions for manipulating maps.</p>[[XQuery 3.1#Maps|Maps]] have been introduced with [[XQuery 3.1]]. =Conventions= <p>All functions in this module are preceded by assigned to the <code>map:</code> prefix, which is linked to the <codenowiki>http://www.w3.org/2005/xpath-functions/map</codenowiki> namespace.</pcode><p>A map is an additional kind of item.</p><p>A map comprises a collation and a set of entries. Each entry comprises a key namespace, which is an arbitrary atomic value, and an arbitrary sequence called statically bound to the associated value. Within a {{Code|map, no two entries have the same key, when compared using the <code>eq</code> operator under the map's collation. It is not necessary that all the keys should be mutually comparable (for example, they can include a mixture of integers and strings)}} prefix. Key values will never be of type <code>xs:untypedAtomic<br/code>, and they will never be the <code>xs:float</code> or <code>xs:double</code> value <code>NaN</code>.</p> <p>The function call <code>map:get($map, $key)</code> can be used to retrieve the value associated with a given key.</p><p>A <em>map</em> can also be viewed as a function from keys to associated values. To achieve this, a map is also a function item. The function corresponding to =Functions= Some examples use the ''map has the signature <code>function('' {{Code|$key week}} defined as xs:anyAtomicValue) as item()*</codepre lang='xquery'>. Calling the function has the same effect as calling the <code>get</code> functiondeclare variable $week : the expression <code>$map($key)</code> returns the same result as <code>get($= map{ 0: "Sun", $key)</code>. For example1: "Mon", if <code>$books-by-isbn</code> is a map whose keys are ISBNs and whose assocated values are <code>book</code> elements2: "Tue", then the expression <code>$books-by-isbn(3: "0470192747Wed")</code> returns the <code>book</code> element with the given ISBN. The fact that a map is a function item allows it to be passed as an argument to higher-order functions that expect a function item as one of their arguments.</p><p>Like all other values, <em>maps</em> are immutable. For example4: "Thu", the <code>map5:remove</code> function creates a new map by removing an entry from an existing map"Fri", but the existing map is not changed by the operation.</p><p>Like sequences, <em>maps</em> have no identity. It is meaningful to compare the contents of two maps, but there is no way of asking whether they are 6: "the same mapSat": two maps with the same content are indistinguishable.</p><p>Because a map is a function item, functions that apply to functions also apply to maps. A map is an anonymous function, so <code>fn:function-name</code> returns the empty sequence}; <code>fn:arity</code> always returns <code>1</code>.</p><p>Maps may be compared using the <code>fn:deep-equal</code> function. The semantics for this function are extended so that when two items are compared, at any level of recursion, the items compare equal if they are both maps, if both use the same collation, if both contain the same set of keys (compared using the <code>eq</code> operator), 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.</p><p>There is no operation to atomize a map or convert it to a string.</ppre>

 {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''| <code><strongpre>map:contains</strong>( $map as map(*), $key as item()xs:anyAtomicType) as xs:boolean</code><br/pre>|-| valign='"top' "| '''Summary'''| <p>Tests whether a supplied map contains an entry for a given key.</p>|-| valign='top' | '''Rules'''| The function <code>map:contains</code> returns Returns true if the <em>map</em> supplied as <code>{{Code|$map</code> }} contains an entry with a key equal to the supplied value of <code>{{Code|$key</code>}}; otherwise it returns false. 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>compared as an instance of {{Code|xs:string</code>}}. If the supplied key is the <code>{{Code|xs:float</code> }} or <code>{{Code|xs:double</code> }} value <code>{{Code|NaN</code>}}, the function returns true if there is an entry whose key is {{Code|NaN}}, or falseotherwise.<pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre>|-| valign='"top' "| '''Examples'''|The expression <code>* {{Code|map:contains($week, 2)</code> }} returns <code>{{Code|true()</code>}}.<br/>The expression <code>* {{Code|map:contains($week, 9)</code> }} returns <code>{{Code|false()</code>}}.<br/>The expression * <code>map:contains(map{}, "xyz")</code> returns <code>{{Code|false()</code>}}.<br/>The expression * <code>map:contains(map{"xyz":=23}, "xyz")</code> returns <code>{{Code|true()</code>}}.<br/>

{| width='100%'| width='120' | '''Signature'''|<pre>map:entry( $key as xs:anyAtomicType, $value as item()*) as map(*)</pre class>|- valign="brushtop"| '''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}}.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:newmerge(( 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")

Unlike the <code>map{...}</code> expression, this technique can be used to construct a map with a variable number of entries, for example:<pre classlang="brush:'xquery"'>map:newmerge(for $b in //book return map:entry($b/isbn, $b))</pre>|-| valign='"top' "| '''Examples'''| The expression <code>{{Code|map:entry("M", "Monday")}} creates </code> returns map { "M": "Monday" }</code>.|} ==map:find== {| width='100%'| width='120' | '''Signature'''|<pre>map:find( $input as item()*, $key as xs:anyAtomicType) as array(*)</pre>|- valign="Mtop"| '''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.|- valign="Mondaytop"| '''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.|} ==map:for-each== {| width='100%'| width='120' | '''Signature'''|<pre>map:for-each( $map as map(*), $action as function(xs:anyAtomicType, item()*) as item()*) as item()*</pre>|- valign="top"| '''Summary'''|Applies the specified {{Code|$action}} to every key/value pair of the supplied {{Code|$map}} and returns the results as a sequence.|- valign="top"| '''Examples'''|The following query adds the keys and values of all map entries and returns {{Code|(3,7)}}:<pre lang='xquery'>map:for-each( map { 1: 2, 3: 4 }, function($key, $value) { $key + $value })</pre>

 {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''| <code><strongpre>map:get</strong>( $map as map(*), $key as item()xs:anyAtomicType) as item()*</code><br/pre>|-| valign='"top' "| '''Summary'''| <p>Returns the value associated with a supplied key in a given map.</p>|-| valign='top' | '''Rules'''| The This function <code>map:get</code> attempts to find an entry within the <em>{{Code|$map</em> supplied as <code>$input</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 <em>''map</em> '' 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>}}.<pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre>|-| valign='"top' "| '''Examples'''| The expression <code>* {{Code|map:get($week, 4)</code> }} returns <code>{{Code|"DonnerstagThu"</code>}}.<br/>The expression <code>* {{Code|map:get($week, 9)</code> }} returns <code>{{Code|()</code>}}. <em>''(When the key is not present, the function returns an empty sequence.).</em><br/>''The expression <code>* {{Code|map:get(map:entry(7,())), 7)</code> }} returns <code>{{Code|()</code>}}. <em>''(An empty sequence as the result can also signify that the key is present and the associated value is an empty sequence.).</em><br/>''

 {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''| <code><strongpre>map:keys</strong>( $map as map(*)) as xs:anyAtomicType*</code><br/pre>|-| valign='"top' "| '''Summary'''| <p>Returns a sequence containing all the key values present in a map.</p>The function takes the supplied {{Code|$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.|-| valign='"top' "| '''RulesExamples'''| The function * <code>map:keys(map { 1: "yes", 2: "no" })</code> takes any returns {{Code|(1,2)}}.|} ==map:merge== {| width='100%'| width='120' | '''Signature'''|<emphpre>map</emph> :merge( $maps as its <code>map(*)*, $inputoptions as map(*) := map { }) as map(*)</codepre> argument |- valign="top"| '''Summary'''| Constructs and returns a new map. The ''map'' is formed by combining the contents of the keys that supplied {{Code|$maps}}. The maps are combined as follows:# There is one entry in the new map for each distinct key present in the map as union of the input maps.# The {{Code|$options}} argument defines how duplicate keys are handled. Currently, a sequence of atomic single option {{Code|duplicates}} exists, and its allowed valuesare {{Code|use-first}}, in implementation{{Code|use-last}}, {{Code|combine}} and {{Code|reject}} (default: {{Code|use-dependent orderfirst}}).|-| valign='"top' "| '''Examples'''| The expression * {{Code|map:merge(())}} creates an empty map.* {{Code|map:merge((map:entry(0, "no"), map:entry(1, "yes")))}} creates <code>map{ 0:keys(map{"no", 1:="yes"}</code>.* The following function adds a seventh entry to an existing map:<pre lang='xquery'>map:merge(($week, 2map { 7:="no---"}))</codepre> returns some permutation * 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>. ):<empre lang='xquery'>map:merge(The result is for $i in implementation-dependent order.1 to 3 return map { 'key': $i }, map { 'duplicates': 'combine' }).</em><br/pre>

 ==map:newput== {|| width='90100%' valign| width='top120' | '''SignaturesSignature'''| <code><strongpre>map:new</strong>put() $map as map(*)</code><br/><code><strong>map:new</strong>(, $maps key as map(*)*) as map(*)</code><br/><code><strong>mapxs:new</strong>(anyAtomicType, $maps value as mapitem(*)*, $coll as xs:string) as map(*)</code><br/pre>|-| valign='"top' "| '''Summary'''| <p>Creates a new map: either an empty map, or a map that combines entries from a number of existing maps.</p>|-| valign='top' | '''Rules'map''| The function <code>map:new</code> constructs and returns a new map. The zero-argument form of the function returns an empty <em>map</em> whose collation is the default collation in the static context. It is equivalent to calling the one-argument form of the function with an empty sequence as the value of the first argument.The one-argument form of the function returns a <em>map</em> that is formed by combining the contents of the maps supplied in the <code>$input</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 function returns a <em>map</em> that is formed by combining the contents of the maps supplied in the <code>$input</code> argument. The collation of the new map is the value of the <code>$collation</code> argument. The supplied maps are combined as follows:<ol> <li> <p> 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 containing the rules entries of the <code>distinct-values</code> function with <code>$collation</code> as the collation. </p> </li> <li> <p> The associated value for each such key is taken from the last map in the input sequence <code>$input</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 <em>implementation-dependent</em> which of them is selected. </p> </li></ol>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.<pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre>{Code|-| valign='top' | '''Examples'''| The expression <code>map:new()</code> returns <code>map{}</code>. <em>(Returns an empty map, whose collation is the default collation from the static context).</em><br/>The expression <code>map:new(())</code> returns <code>$map{}</code>. <em>(Returns an empty map, whose collation is the default collation from the static context).</em><br/>The expression <code>map:new(map:entry(0, "no"), map:entry(1, "yes"))</code> returns <code>map{0:="no", 1:="yes"}</code>. <em>(Returns and a map with two entries; the collation of the map is the default collation from the static context).</em><br/>The expression <code>map:new(map:entry(0, "no"), map:entry(1, "yes"))</code> returns <code>mapcomposed by {{0:="no", 1:="yes"Code|$key}}</code>. <em>(Returns a map with two entries; the collation of the map is the default collation from the static context).</em><br/>The expression <code>map:new((and {{Code|$week, map{7:"Unbekannt"value}))</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag", 7:"Unbekannt"}</code>. <em>(The value semantics of the existing map is unchanged; a new map is created containing all the entries from <code>$week</code>, supplemented with a new entry.).</em><br/>The expression this function are equivalent to <code>map:newmerge(($week, map{6:"Sonnabend"}))</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag"$key, 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Sonnabend"}</code>. <em>(The value of the existing map is unchanged; a new map is created containing all the entries from <code>$week</code>, with one entry replaced by a new entry. Both input maps contain an entry with the key value <code>6</code>; the one used in the result is the one that comes last in the input sequence.).</em><br/>The expression <code>map:new((map{"A":=1}, $map{"a:=2"}), "http://collation.example.com/caseblind")</code> returns <code>map{"a":=2}</code>. <em>(Assuming that the keys of the two entries are equal under the rules of the chosen collation, only one of the entries can appear in the result; the one that is chosen is the one from the last map in the input sequence. If both entries were in the same map, it would be implementation-dependent which was chosen.).</em><br/>

 {|| 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'''| <p>Constructs a new map by removing an entry entries from an existing map.</p>|-| valign='top' | '''Rules'''| The function <code>map:remove</code> returns a new <em>map</em>. 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<pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre>.|-| valign='"top' "| '''Examples'''| The expression <code>* {{Code|map:remove($week, 4)</code> returns }} creates <code>map{0:="SonntagSun", 1:="MontagMon", 2:="DienstagTue", 3:="MittwochWed", 5:"FreitagFri", 6:"SamstagSat"}</code>.<br/>The expression <code>* {{Code|map:remove($week, 23)</code> returns }} creates <code>map{0:="SonntagSun", 1:="MontagMon", 2:="DienstagTue", 3:="MittwochWed", 4:="DonnerstagThu", 5:"FreitagFri", 6:"SamstagSat"}</code>.<br/>

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