Difference between revisions of "Map Module"
Line 3: | Line 3: | ||
=Introduction= | =Introduction= | ||
− | A map is an additional kind of item. It 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 | + | A map is an additional kind of item. It 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 {{Code|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 {{Code|xs:untypedAtomic}}, and they will never be the {{Code|xs:float}} or {{Code|xs:double}} value {{Code|NaN}}. |
The function call <code>[[#map:get|map:get($map, $key)]]</code> can be used to retrieve the value associated with a given key. | The function call <code>[[#map:get|map:get($map, $key)]]</code> 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 | + | 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 {{Code|function($key as xs:anyAtomicType) as item()*}}. Calling the function has the same effect as calling the {{Code|get}} function: the expression {{Code|$map($key)}} returns the same result as {{Code|map:get($map, $key)}}. For example, if {{Code|$books-by-isbn}} is a map whose keys are ISBNs and whose associated values are {{Code|book}} elements, then the expression {{Code|$books-by-isbn("0470192747")}} returns the {{Code|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. As an example, the following query uses the higher-order function {{Code|fn:map($f, $seq)}} to extract all bound values from a ''map'': |
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
Line 14: | Line 14: | ||
</pre> | </pre> | ||
− | This returns some permutation of | + | This returns some permutation of {{Code|(42, 'baz', 456)}}. |
− | Like all other values, ''maps'' are immutable. For example, the | + | Like all other values, ''maps'' are immutable. For example, the {{Code|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. | 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 | + | 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}} returns the empty sequence; {{Code|fn:function-arity}} always returns {{Code|1}}. |
− | Maps may be compared using the | + | Maps may be compared using the {{Code|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 {{Code|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 {{Code|fn:deep-equal}} 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: | 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: | ||
Line 34: | Line 34: | ||
</pre> | </pre> | ||
− | Some examples use the ''map'' | + | Some examples use the ''map'' {{Code|$week}} defined as: |
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
declare variable $week as map(*) := map { | declare variable $week as map(*) := map { | ||
Line 50: | Line 50: | ||
=Conventions= | =Conventions= | ||
− | All functions in this module are assigned to the | + | All functions in this module are assigned to the {{Code|http://www.w3.org/2005/xpath-functions/map}} namespace, which is statically bound to the {{Code|map}} prefix.<br/> |
=Functions= | =Functions= | ||
Line 57: | Line 57: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:collation|$map as map(*)|xs:string}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns the collation URI of the ''map'' supplied as | + | | Returns the collation URI of the ''map'' supplied as {{Code|$map}}. |
|} | |} | ||
Line 66: | Line 66: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:contains|$map as map(*), $key as item()|xs:boolean}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns true if the ''map'' supplied as | + | | Returns true if the ''map'' supplied as {{Code|$map}} contains an entry with a key equal to the supplied value of {{Code|$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 {{Code|$key}}. |
− | If the supplied key is | + | 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 false. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * {{Code|map:contains($week, 2)}} returns {{Code|true()}}. |
− | * | + | * {{Code|map:contains($week, 9)}} returns {{Code|false()}}. |
− | * <code>map:contains(map{}, "xyz")</code> returns | + | * <code>map:contains(map{}, "xyz")</code> returns {{Code|false()}}. |
− | * <code>map:contains(map{ "xyz":=23 }, "xyz")</code> returns | + | * <code>map:contains(map{ "xyz":=23 }, "xyz")</code> returns {{Code|true()}}. |
|} | |} | ||
Line 83: | Line 83: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:entry|$key as item(), $value as item()*|map(*)}} |
|- | |- | ||
| '''Summary''' | | '''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 | + | | 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}}, and its associated value is {{Code|$value}}. 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 supplied {{Code|$map}} is returned unchanged. |
− | The function | + | The function {{Code|map:entry}} 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: |
<pre class="brush:xquery"> | <pre class="brush:xquery"> | ||
Line 106: | Line 106: | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * {{Code|map:entry("M", "Monday")}} creates a map with the values <code>{ "M":="Monday" }</code>. |
|} | |} | ||
Line 112: | Line 112: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:get|$map as map(*), $key as item()|item()*}} |
|- | |- | ||
| '''Summary''' | | '''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 | + | |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|$map}} that has a key equal to the supplied value of {{Code|$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 {{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 | + | 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 | + | Invoking the ''map'' as a function item has the same effect as calling {{Code|get}}: that is, when {{Code|$map}} is a map, the expression {{Code|$map($K)}} is equivalent to {{Code|get($map, $K)}}. Similarly, the expression {{Code|get(get(get($map, 'employee'), 'name'), 'first')}} can be written as {{Code|$map('employee')('name')('first')}}. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * {{Code|map:get($week, 4)}} returns {{Code|"Donnerstag"}}. |
− | * | + | * {{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.).'' |
|} | |} | ||
Line 129: | Line 129: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:keys|$map as map(*)|xs:anyAtomicType*}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns a sequence containing all the key values present in a map. The function takes any ''map'' as its | + | |Returns a sequence containing all the key values present in a map. The function takes any ''map'' as its {{Code|$map}} argument and returns the keys that are present in the map as a sequence of atomic values, in implementation-dependent order. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * <code>map:keys(map{ 1:="yes", 2:="no" })</code> returns some permutation of | + | * <code>map:keys(map{ 1:="yes", 2:="no" })</code> returns some permutation of {{Code|(1,2)}} ''(the result is in implementation-dependent order).'' |
|} | |} | ||
Line 142: | Line 142: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:new||map(*)}}<br/>{{Func|map:new|$maps as map(*)*|map(*)}}<br/>{{Func|map:new|$maps as map(*)*, $coll as xs:string|map(*)}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
| 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. | | 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 | + | The one-argument form of the function returns a ''map'' that is formed by combining the contents of the maps supplied in the {{Code|$maps}} 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 ''map'' that is formed by combining the contents of the maps supplied in the | + | The two-argument form of the function returns a ''map'' that is formed by combining the contents of the maps supplied in the {{Code|$maps}} argument. The collation of the new map is the value of the {{Code|$coll}} 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 | + | # 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}} function with {{Code|$coll}} as the collation. |
− | # The associated value for each such key is taken from the last map in the input sequence | + | # The associated value for each such key is taken from the last map in the input sequence {{Code|$maps}} 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. |
− | There is no requirement that the supplied input maps should have the same or compatible types. The type of a map (for example | + | 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)}}) is descriptive of the entries it currently contains, but is not a constraint on how the map may be combined with other maps. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * {{Code|map:new()}} creates an empty map. |
− | * | + | * {{Code|map:new(())}} creates an empty map. |
− | * | + | * {{Code|map:new(map:entry(0, "no"), map:entry(1, "yes"))}} creates a map with the values <code>{ 0:="no", 1:="yes" }</code>. |
* <code>map:new(($week, map{ 7:="Unbekannt" }))</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>. | * <code>map:new(($week, map{ 7:="Unbekannt" }))</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>. | ||
* <code>map:new(($week, 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>. | * <code>map:new(($week, 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>. | ||
Line 166: | Line 166: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:remove|$map as map(*), $key as item()|map(*)}}<br/> |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Constructs a new map by removing an entry from an existing map. The collation of the new map is the same as the collation of the map supplied as | + | | Constructs a new map by removing an entry from an existing map. The collation of the new map is the same as the collation of the map supplied as {{Code|$map}}. The entries in the new map correspond to the entries of {{Code|$map}}, excluding any entry whose key is equal to {{Code|$key}}. |
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 | ||
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * {{Code|map:remove($week, 4)}} creates a map with the values <code>{ 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 5:="Freitag", 6:="Samstag" }</code>. |
− | * | + | * {{Code|map:remove($week, 23)}} creates a map with the values <code>{ 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag" }</code>. |
|} | |} | ||
Line 181: | Line 181: | ||
{| | {| | ||
| width='90' | '''Signatures''' | | width='90' | '''Signatures''' | ||
− | | | + | |{{Func|map:size|$map as map(*)|xs:integer}}<br/> |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns a the number of entries in the supplied map. The function takes any ''map'' as its | + | | Returns a the number of entries in the supplied map. The function takes any ''map'' as its {{Code|$map}} argument and returns the number of entries that are present in the map. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * {{Code|map:size(map:new())}} returns {{Code|0}}. |
− | * <code>map:size(map{ "true":=1, "false":=0 })</code> returns | + | * <code>map:size(map{ "true":=1, "false":=0 })</code> returns {{Code|2}}. |
|} | |} | ||
[[Category:XQuery]] | [[Category:XQuery]] |
Revision as of 16:12, 26 May 2012
This XQuery Module contains functions for manipulating maps. The following documentation is derived from an XQuery 3.0 Functions and Operators working draft proposal written by Michael H. Kay, and is not part of the official standard yet.
Contents
Introduction
A map is an additional kind of item. It 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:anyAtomicType) as item()*
. Calling the function has the same effect as calling the get
function: the expression $map($key)
returns the same result as map:get($map, $key)
. For example, if $books-by-isbn
is a map whose keys are ISBNs and whose associated 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. As an example, the following query uses the higher-order function fn:map($f, $seq)
to extract all bound values from a map:
let $map := map { 'foo' := 42, 'bar' := 'baz', 123 := 456 } return fn:map($map, map:keys($map))
This returns some permutation of (42, 'baz', 456)
.
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:function-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. The following XQuery snippet shows how the contents of a map can be serialized:
let $map := map { 1:='a', 2:='b' } return string-join( for $m in map:keys($map) return concat($m, ':=', $map($m)), ', ' )
Some examples use the map $week
defined as:
declare variable $week as map(*) := map { 0:="Sonntag", 1:="Montag", 2:="Dienstag", 3:="Mittwoch", 4:="Donnerstag", 5:="Freitag", 6:="Samstag" };
Conventions
All functions in this module are assigned to the http://www.w3.org/2005/xpath-functions/map
namespace, which is statically bound to the map
prefix.
Functions
map:collation
Signatures | map:collation($map as map(*)) as xs:string
|
Summary | Returns the collation URI of the map supplied as $map .
|
map:contains
Signatures | map:contains($map as map(*), $key as item()) as xs:boolean
|
Summary | 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 |
Examples |
|
map:entry
Signatures | map:entry($key as item(), $value as item()*) as map(*)
|
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 $key , and its associated value is $value . 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 |
|
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. This function attempts to find an entry within the map supplied as $map 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 |
Examples |
|
map:keys
Signatures | map:keys($map as map(*)) as xs:anyAtomicType*
|
Summary | Returns a sequence containing all the key values present in a map. The function takes any map as its $map argument and returns the keys that are present in the map as a sequence of atomic values, in implementation-dependent order.
|
Examples |
|
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 | 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 |
Examples |
|
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. 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 |
Examples |
|
map:size
Signatures | map:size($map as map(*)) as xs:integer |
Summary | Returns a the number of entries in the supplied map. The function takes any map as its $map argument and returns the number of entries that are present in the map.
|
Examples |
|