Difference between revisions of "Map Module"
LeoWoerteler (talk | contribs) |
LeoWoerteler (talk | contribs) |
||
Line 33: | Line 33: | ||
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 function returns false. | 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 function returns false. | ||
<pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", | <pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", | ||
− | 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre> | + | 4:="Donnerstag", 5:="Freitag", 6:="Samstag"}</pre> |
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
Line 85: | Line 85: | ||
Invoking the <em>map</em> as a function item has the same effect as calling <code>get</code>: that is, when <code>$map</code> is a map, the expression <code>$map($K)</code> is equivalent to <code>get($map, $K)</code>. Similarly, the expression <code>get(get(get($map, 'employee'), 'name'), 'first')</code> can be written as <code>$map('employee')('name')('first')</code>. | Invoking the <em>map</em> as a function item has the same effect as calling <code>get</code>: that is, when <code>$map</code> is a map, the expression <code>$map($K)</code> is equivalent to <code>get($map, $K)</code>. Similarly, the expression <code>get(get(get($map, 'employee'), 'name'), 'first')</code> can be written as <code>$map('employee')('name')('first')</code>. | ||
<pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", | <pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", | ||
− | 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre> | + | 4:="Donnerstag", 5:="Freitag", 6:="Samstag"}</pre> |
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
Line 141: | Line 141: | ||
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. | 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", | <pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", | ||
− | 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre> | + | 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag"}</pre> |
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
Line 149: | Line 149: | ||
The expression <code>map:new(map:entry(0, "no"), map:entry(1, "yes"))</code> returns <code>map{0:="no", 1:="yes"}</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(map:entry(0, "no"), map:entry(1, "yes"))</code> returns <code>map{0:="no", 1:="yes"}</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(map:entry(0, "no"), map:entry(1, "yes"))</code> returns <code>map{0:="no", 1:="yes"}</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(map:entry(0, "no"), map:entry(1, "yes"))</code> returns <code>map{0:="no", 1:="yes"}</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(($week, map{7:"Unbekannt"}))</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag", 7:"Unbekannt"}</code>. <em>(The value 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 <code>map:new(($week, map{7:="Unbekannt"}))</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag", 7:="Unbekannt"}</code>. <em>(The value 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 <code>map:new(($week, map{6:"Sonnabend"}))</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 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(($week, map{6:="Sonnabend"}))</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 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/> | 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/> | ||
|} | |} | ||
Line 165: | Line 165: | ||
No failure occurs if the input map contains no entry with the supplied key; the input map is returned unchanged | No failure occurs if the input map contains no entry with the supplied key; the input map is returned unchanged | ||
<pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", | <pre class="brush:xquery">let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", | ||
− | 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</pre> | + | 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag"}</pre> |
|- | |- | ||
| valign='top' | '''Examples''' | | valign='top' | '''Examples''' | ||
− | | The expression <code>map:remove($week, 4)</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 5:"Freitag", 6:"Samstag"}</code>.<br/> | + | | The expression <code>map:remove($week, 4)</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 5:="Freitag", 6:="Samstag"}</code>.<br/> |
− | The expression <code>map:remove($week, 23)</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:"Freitag", 6:"Samstag"}</code>.<br/> | + | The expression <code>map:remove($week, 23)</code> returns <code>map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag"}</code>.<br/> |
|} | |} | ||
==map:size== | ==map:size== |
Revision as of 23:04, 22 April 2011
This module contains XQuery Functions for manipulating maps.
All functions are preceded by the map:
prefix, which is linked to the http://www.w3.org/2005/xpath-functions/map
namespace.
A map is an additional kind of item.
A map comprises a collation and a set of entries. Each entry comprises a key which is an arbitrary atomic value, and an arbitrary sequence called the associated value. Within a map, no two entries have the same key, when compared using the eq
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). Key values will never be of type xs:untypedAtomic
, and they will never be the xs:float
or xs:double
value NaN
.
The function call map:get($map, $key)
can be used to retrieve the value associated with a given key.
A map 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 the map has the signature function($key as xs:anyAtomicValue) as item()*
. Calling the function has the same effect as calling the get
function: the expression $map($key)
returns the same result as get($map, $key)
. For example, if $books-by-isbn
is a map whose keys are ISBNs and whose assocated values are book
elements, then the expression $books-by-isbn("0470192747")
returns the book
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.
Like all other values, maps are immutable. For example, the map:remove
function creates a new map by removing an entry from an existing map, but the existing map is not changed by the operation.
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.
Because a map is a function item, functions that apply to functions also apply to maps. A map is an anonymous function, so fn:function-name
returns the empty sequence; fn:arity
always returns 1
.
Maps may be compared using the fn:deep-equal
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 eq
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 fn:deep-equal
function.
There is no operation to atomize a map or convert it to a string.
Contents
map:collation
Signatures | map:collation($map as map(*)) as xs:string |
Summary | Returns the URI of the supplied map's collation. |
Rules | The function map:collation returns the collation URI of the map supplied as $input .
|
map:contains
Signatures | map:contains($map as map(*), $key as item()) as xs:boolean |
Summary | Tests whether a supplied map contains an entry for a given key. |
Rules | The function map:contains returns true if the map supplied as $map contains an entry with a key equal to the supplied value of $key ; 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 $key .
If the supplied key is let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag"} |
Examples |
The expression |
map:entry
Signatures | map:entry($key as item(), $value as item()*) as map(*) |
Summary | The function |
Rules | If the supplied key is xs:untypedAtomic , it is converted to xs:string . If the supplied key is the xs:float or xs:double value NaN , the supplied $map is returned unchanged.
The function map:new(( map:entry("Su", "Sunday"), map:entry("Mo", "Monday"), map:entry("Tu", "Tuesday"), map:entry("We", "Wednesday"), map:entry("Th", "Thursday"), map:entry("Fr", "Friday"), map:entry("Sa", "Saturday") )) Unlike the map:new(for $b in //book return map:entry($b/isbn, $b)) |
Examples | The expression map:entry("M", "Monday") returns map{"M":="Monday"} .
|
map:get
Signatures | map:get($map as map(*), $key as item()) as item()* |
Summary | Returns the value associated with a supplied key in a given map. |
Rules | The function map:get attempts to find an entry within the map supplied as $input that has a key equal to the supplied value of $key . If there is such an entry, it returns the associated value; otherwise it returns an empty sequence. The equality comparison uses the map's collation; no error occurs 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 . If the supplied key is the xs:float or xs:double value NaN , the function returns an empty sequence.
A return value of let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag"} |
Examples |
The expression |
map:keys
Signatures | map:keys($map as map(*)) as xs:anyAtomicType* |
Summary | Returns a sequence containing all the key values present in a map. |
Rules | The function map:keys takes any map as its $input argument and returns the keys that are present in the map as a sequence of atomic values, in implementation-dependent order.
|
Examples | The expression map:keys(map{1:="yes", 2:="no"}) returns some permutation of (1,2) . (The result is in implementation-dependent order.). |
map:new
Signatures | map:new() as map(*) map:new($maps as map(*)*) as map(*) map:new($maps as map(*)*, $coll as xs:string) as map(*) |
Summary | Creates a new map: either an empty map, or a map that combines entries from a number of existing maps. |
Rules | The function map:new constructs and returns a new map. The zero-argument form of the function returns an empty map 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 map that is formed by combining the contents of the maps supplied in the
There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag"} |
Examples |
The expression |
map:remove
Signatures | map:remove($map as map(*), $key as item()) as map(*) |
Summary | Constructs a new map by removing an entry from an existing map. |
Rules | The function map:remove returns a new map. The collation of the new map is the same as the collation of the map supplied as $map . The entries in the new map correspond to the entries of $map , excluding any entry whose key is equal to $key .
No failure occurs if the input map contains no entry with the supplied key; the input map is returned unchanged let $week := map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag"} |
Examples | The expression map:remove($week, 4) returns map{0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 5:="Freitag", 6:="Samstag"} .The expression |
map:size
Signatures | map:size($map as map(*)) as xs:integer |
Summary | Returns a the number of entries in the supplied map. |
Rules | The function map:size takes any map as its $input argument and returns the number of entries that are present in the map.
|
Examples | The expression map:size(map:new()) returns 0 .The expression map:size(map{"true":=1, "false":0}) returns 2 . |