Difference between revisions of "Map Module"
Line 44: | Line 44: | ||
| '''Summary''' | | '''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. | | 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: | + | 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 class="brush:xquery"> | <pre class="brush:xquery"> | ||
− | map: | + | map:merge(( |
map:entry("Su", "Sunday"), | map:entry("Su", "Sunday"), | ||
map:entry("Mo", "Monday"), | map:entry("Mo", "Monday"), | ||
Line 59: | Line 59: | ||
Unlike the <code>map{ ... }</code> expression, this technique can be used to construct a map with a variable number of entries, for example: | Unlike the <code>map{ ... }</code> expression, this technique can be used to construct a map with a variable number of entries, for example: | ||
− | <pre class="brush:xquery">map: | + | <pre class="brush:xquery">map:merge(for $b in //book return map:entry($b/isbn, $b))</pre> |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 96: | Line 96: | ||
|} | |} | ||
− | ==map: | + | ==map:merge== |
+ | |||
+ | {{Mark|Added with Version 8.0}} (replacing {{Code|map:new}}): | ||
+ | |||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map: | + | |{{Func|map:merge|$inputs as map(*)*|map(*)}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Constructs and returns a new map. The | + | | Constructs and returns a new map. The ''map'' is formed by combining the contents of the maps supplied in the {{Code|$inputs}} 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, where keys are considered distinct according to the rules of the {{Code|distinct-values}} function. | # 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. | ||
Line 112: | Line 114: | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * {{Code|map: | + | * {{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>. | |
− | * {{Code|map: | + | * <code>map:merge(($week, map{ 7: "Unbekannt" }))</code> creates <code>map { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Samstag", 7: "Unbekannt" }</code>. |
− | * <code>map: | + | * <code>map:merge(($week, map{ 6: "Sonnabend" }))</code> creates <code>map { 0: "Sonntag", 1: "Montag", 2: "Dienstag", 3: "Mittwoch", 4: "Donnerstag", 5: "Freitag", 6: "Sonnabend" }</code>. |
− | * <code>map: | ||
|} | |} | ||
Line 144: | Line 145: | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * {{Code|map:size(map: | + | * {{Code|map:size(map:merge(()))}} returns {{Code|0}}. |
* <code>map:size(map{ "true": 1, "false": 0 })</code> returns {{Code|2}}. | * <code>map:size(map{ "true": 1, "false": 0 })</code> returns {{Code|2}}. | ||
|} | |} | ||
Line 170: | Line 171: | ||
* Introduction on maps moved to [[XQuery 3.1#Maps|XQuery 3.1]]. | * Introduction on maps moved to [[XQuery 3.1#Maps|XQuery 3.1]]. | ||
* Removed: support for collations (in accordance with the XQuery 3.1 spec). | * 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}}. | * 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}}. | ||
Revision as of 13:35, 7 August 2014
This XQuery Module contains functions for manipulating maps, which will officially be introduced with XQuery 3.1.
Contents
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
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" };
map:contains
Signatures | map:contains($input as map(*), $key as xs:anyAtomicType) as xs:boolean
|
Summary | Returns true if the map supplied as $input contains an entry with a key equal to the supplied value of $key ; otherwise it returns false. No error is raised 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 xs:anyAtomicType, $value as item()*) as map(*)
|
Summary | Creates a new map containing a single entry. 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 compared as an instance of xs:string . If the supplied key is the xs:float or xs:double value NaN , the function returns the value in the entry whose key is NaN , or the empty sequence otherwise.
The function map:merge(( 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:merge(for $b in //book return map:entry($b/isbn, $b)) |
Examples |
|
map:get
Signatures | map:get($input as map(*), $key as xs:anyAtomicType) 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 $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. No error is raised 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($input 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 $input 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 |
|
map:merge
Template:Mark (replacing map:new
):
Signatures | map:merge($inputs as map(*)*) as map(*)
|
Summary | Constructs and returns a new map. The map is formed by combining the contents of the maps supplied in the $inputs argument. The maps are combined as follows:
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($input as map(*), $key as xs:anyAtomicType) as map(*) |
Summary | Constructs a new map by removing an entry from an existing map. The entries in the new map correspond to the entries of $input , 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($input as map(*)) as xs:integer |
Summary | Returns a the number of entries in the supplied map. The function takes any map as its $input argument and returns the number of entries that are present in the map.
|
Examples |
|
map:serialize
Signatures | map:serialize($input as map(*)) as xs:string |
Summary | 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. In most cases, it cannot be used for reconstructing the original map. |
Examples |
|
Changelog
- Version 8.0
- Introduction on maps moved to XQuery 3.1.
- Removed: support for collations (in accordance with the XQuery 3.1 spec).
- Removed:
map:new
(replaced withmap:merge
) - Updated: aligned with latest specification: compare keys of type
xs:untypedAtomic
asxs:string
instances, storexs:float
orxs:double
valueNaN
.
- Version 7.8
- Updated: map syntax
map { 'key': 'value' }
- Added: map:serialize
- Version 7.7.1
- Updated: alternative map syntax without
map
keyword and:
as key/value delimiter (e.g.:{ 'key' : 'value' })