Difference between revisions of "Map Module"
Line 23: | Line 23: | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map:contains|$ | + | |{{Func|map:contains|$inpu as map(*), $key as xs:anyAtomicType|xs:boolean}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns true if the ''map'' supplied as {{Code|$ | + | | Returns true if the ''map'' supplied as {{Code|$inpu}} 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 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 false. | 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. | ||
|- | |- | ||
Line 43: | Line 43: | ||
|- | |- | ||
| '''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 converted to {{Code|xs:string}}. If the supplied key is the {{Code|xs:float}} or {{Code|xs:double}} value {{Code|NaN}}, the supplied {{Code|$ | + | | 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 converted to {{Code|xs:string}}. If the supplied key is the {{Code|xs:float}} or {{Code|xs:double}} value {{Code|NaN}}, the supplied {{Code|$inpu}} is returned unchanged. |
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: | 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: | ||
Line 69: | Line 69: | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map:get|$ | + | |{{Func|map:get|$inpu as map(*), $key as xs:anyAtomicType|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 {{Code|$ | + | |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|$inpu}} 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. No error is raised 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 {{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}}. | 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 {{Code|get}}: that is, when {{Code|$ | + | Invoking the ''map'' as a function item has the same effect as calling {{Code|get}}: that is, when {{Code|$inpu}} is a map, the expression {{Code|$inpu($K)}} is equivalent to {{Code|get($inpu, $K)}}. Similarly, the expression {{Code|get(get(get($inpu, 'employee'), 'name'), 'first')}} can be written as {{Code|$inpu('employee')('name')('first')}}. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 86: | Line 86: | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map:keys|$ | + | |{{Func|map:keys|$inpu 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 {{Code|$ | + | |Returns a sequence containing all the key values present in a map. The function takes any ''map'' as its {{Code|$inpu}} argument and returns the keys that are present in the map as a sequence of atomic values, in implementation-dependent order. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 99: | Line 99: | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map:new||map(*)}}<br/>{{Func|map:new|$ | + | |{{Func|map:new||map(*)}}<br/>{{Func|map:new|$inpus as map(*)*|map(*)}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
| Constructs and returns a new map. The zero-argument form of the function returns an empty ''map''. 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''. 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 {{Code|$ | + | The one-argument form of the function returns a ''map'' that is formed by combining the contents of the maps supplied in the {{Code|$inpus}} 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}} 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. | ||
− | # The associated value for each such key is taken from the last map in the input sequence {{Code|$ | + | # The associated value for each such key is taken from the last map in the input sequence {{Code|$inpus}} that contains an entry with this key. |
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. | 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. | ||
Line 122: | Line 122: | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map:remove|$ | + | |{{Func|map:remove|$inpu as map(*), $key as xs:anyAtomicType|map(*)}}<br/> |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Constructs a new map by removing an entry from an existing map. The entries in the new map correspond to the entries of {{Code|$ | + | | Constructs a new map by removing an entry from an existing map. The entries in the new map correspond to the entries of {{Code|$inpu}}, 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 | ||
|- | |- | ||
Line 137: | Line 137: | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map:size|$ | + | |{{Func|map:size|$inpu as map(*)|xs:integer}}<br/> |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | | Returns a the number of entries in the supplied map. The function takes any ''map'' as its {{Code|$ | + | | Returns a the number of entries in the supplied map. The function takes any ''map'' as its {{Code|$inpu}} argument and returns the number of entries that are present in the map. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
Line 152: | Line 152: | ||
{| width='100%' | {| width='100%' | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|map:serialize|$ | + | |{{Func|map:serialize|$inpu as map(*)|xs:string}}<br/> |
|- | |- | ||
| '''Summary''' | | '''Summary''' |
Revision as of 11:08, 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($inpu as map(*), $key as xs:anyAtomicType) as xs:boolean
|
Summary | Returns true if the map supplied as $inpu 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 converted to xs:string . If the supplied key is the xs:float or xs:double value NaN , the supplied $inpu 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($inpu 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 $inpu 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($inpu 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 $inpu 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($inpus as map(*)*) as map(*)
|
Summary | Constructs and returns a new map. The zero-argument form of the function returns an empty map. 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($inpu 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 $inpu , 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($inpu as map(*)) as xs:integer |
Summary | Returns a the number of entries in the supplied map. The function takes any map as its $inpu argument and returns the number of entries that are present in the map.
|
Examples |
|
map:serialize
Signatures | map:serialize($inpu 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).
- 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' })