http://www.zorba-xquery.com/modules/store/data-structures/unordered-map

Description

Before using any of the functions below please remember to import the module namespace:

import module namespace map = "http://www.zorba-xquery.com/modules/store/data-structures/unordered-map";

This module defines a set of functions for working with maps. A map is identified by a QName and can be created using the map:create or map:create-transient functions and deleted using the map:delete function, respectively.

The lifetime of a transient map is limited by the execution of the current XQuery program. A non-transient (or persistent) map lives until it is explicitly deleted. Accordingly, it's also available to other XQuery programs.

The key of a particular entry in the map can consist of a tuple of atomic values (called attributes). The actual type of each attribute is determined when the map is created. The value of each attribute can be an arbitrary sequence of items.

See also

Data Lifecycle

http://www.zorba-xquery.com/errors

Author

Matthias Brantner

XQuery version and encoding

xquery version "3.0" encoding "utf-8";

Namespaces

anhttp://www.zorba-xquery.com/annotations
errhttp://www.w3.org/2005/xqt-errors
maphttp://www.zorba-xquery.com/modules/store/data-structures/unordered-map
verhttp://www.zorba-xquery.com/options/versioning
zerrhttp://www.zorba-xquery.com/errors

Function Summary

 available-maps() as xs:QName* external

The function returns a sequence of QNames of the maps that are available.

   create-transient($name as xs:QName, $key-type as xs:QName) as empty-sequence() external

Create a transient map with a given name and a set of type identifiers for each key attribute.

   create($name as xs:QName, $key-type as xs:QName) as empty-sequence() external

Create a map with a given name and a set of type identifiers for each key attribute.

  delete($name as xs:QName) as empty-sequence() external

Destroys the map with the given name.

  get($name as xs:QName, $key as xs:anyAtomicType?) as item()* external

Returns the value of the entry with the given key from the map.

   insert($name as xs:QName, $value as item()*, $key as xs:anyAtomicType?) as empty-sequence() external

Inserts a new entry into the map with the given name.

 is-transient($name as xs:QName) as xs:boolean external

The function returns true if the map identified by the given QName is transient, false otherwise.

 keys($name as xs:QName) as node()* external

Returns the keys of all entries of a map.

   remove($name as xs:QName, $key as xs:anyAtomicType?) as empty-sequence() external

Removes an entry identified by the given key from the map.

 size($name as xs:QName) as xs:integer external

The number of entries in a map.

Functions

available-maps#0

declare function map:available-maps() as xs:QName* external

The function returns a sequence of QNames of the maps that are available. The sequence will be empty if there are no maps.

Returns

  • xs:QName*

    A sequence of QNames, one for each available map, or an emtpy sequence.

create-transient#2

declare %an:variadic %an:sequential function map:create-transient(
    $name as xs:QName,
    $key-type as xs:QName
) as empty-sequence() external

Create a transient map with a given name and a set of type identifiers for each key attribute. Note that the function is variadic and might take an arbitrary number of type identifiers for the key attributes.

Parameters

  • $name as xs:QName
    the name of the map
  • $key-type as xs:QName
    an arbitrary number of types, one for each key attribute.

Returns

  • empty-sequence()

    the function is sequential and immediately creates the corresponding map but returns the empty-sequence.

Errors

  • err:XPTY0004 if any of the attribute types is not a subtype of xs:anyAtomicType.
  • zerr:ZSTR0001 if a map with the given name already exists.

create#2

declare %an:variadic %an:sequential function map:create(
    $name as xs:QName,
    $key-type as xs:QName
) as empty-sequence() external

Create a map with a given name and a set of type identifiers for each key attribute. Note that the function is variadic and might take an arbitrary number of type identifiers for the key attributes. Also note that the function is sequential and immediately creates the map in the store.

Parameters

  • $name as xs:QName
    the name of the map
  • $key-type as xs:QName
    an arbitrary number of types, one for each key attribute.

Returns

  • empty-sequence()

    the function is sequential and immediately creates the corresponding map but returns the empty-sequence.

Errors

  • err:XPTY0004 if any of the attribute types is not a subtype of xs:anyAtomicType.
  • zerr:ZSTR0001 if a map with the given name already exists.

delete#1

declare %an:sequential function map:delete(
    $name as xs:QName
) as empty-sequence() external

Destroys the map with the given name.

Parameters

  • $name as xs:QName
    the name of the map to delete

Returns

  • empty-sequence()

    the function is sequential and immediately deletes the map but returns the empty-sequence.

Errors

  • zerr:ZDDY0023 if a map with the given name does not exist.

get#2

declare %an:variadic function map:get(
    $name as xs:QName,
    $key as xs:anyAtomicType?
) as item()* external

Returns the value of the entry with the given key from the map. Note that it is possible to insert entries with empty key attributes. However as the getting the entries is based on the "eq" comparison and as "eq" with an empty sequence always return false, it is not possible to retrieve these entries.

Parameters

  • $name as xs:QName
    the name of the map
  • $key as xs:anyAtomicType

Returns

  • item()*

    the value of the entry in the map identified by the given key. The empty-sequence will be returned if no entry with the given key is contained in the map.

Errors

  • zerr:ZDDY0023 if a map with the given name does not exist.
  • zerr:ZDDY0025 if the given number of key attributes does not match the number of key attributes specified when creating the map (see the map:create function).
  • zerr:ZXQD0005 if any of the given key attributes can not be cast (or is not a subtype) of the corresponding key attribute specified when creating the map.

See also

map:create

insert#3

declare %an:variadic %an:sequential function map:insert(
    $name as xs:QName,
    $value as item()*,
    $key as xs:anyAtomicType?
) as empty-sequence() external

Inserts a new entry into the map with the given name. Note that the function is variadic and might take an arbitrary number of key attributes. If an entry with the given key already exists in the map, the value sequences of the existing entry and the sequence passed using $value argument are concatenated. Note that it is possible to insert entries with empty key attributes. However as the getting the entries is based on the "eq" comparison and as "eq" with an empty sequence always return false, it is not possible to retrieve these entries.

Parameters

  • $name as xs:QName
    the name of the map
  • $value as item()
    the value of the entry to insert
  • $key as xs:anyAtomicType
    an arbitrary number of key attributes.

Returns

  • empty-sequence()

    the function is sequential and immediately inserts the entry into the map but returns the empty-sequence.

Errors

  • zerr:ZDDY0023 if a map with the given name does not exist.
  • zerr:ZDDY0025 if the given number of key attributes does not match the number of key attributes specified when creating the map (see the map:create function).
  • zerr:ZXQD0005 if any of the given key attributes can not be cast (or is not a subtype) of the corresponding key attribute specified when creating the map.

See also

map:create

is-transient#1

declare function map:is-transient(
    $name as xs:QName
) as xs:boolean external

The function returns true if the map identified by the given QName is transient, false otherwise.

Parameters

  • $name as xs:QName
    the name of the map

Returns

  • xs:boolean

    true if the map is transient, false otherwise.

Errors

  • zerr:ZDDY0023 if a map with the given name does not exist.

keys#1

declare function map:keys(
    $name as xs:QName
) as node()* external

Returns the keys of all entries of a map. The keys are returned as sequence of nodes of the form:

 <key xmlns="http://www.zorba-xquery.com/modules/store/data-structures/unordered-map">
   <attribute value="key1_value"/>
   <attribute value="key2_value"/>
   <attribute value="key3_value"/>
 </key>
 
The following condition always holds: map:size($name) eq fn:count(map:keys($name))

Parameters

  • $name as xs:QName
    the name of the map

Returns

  • node()*

    all keys in the map.

Errors

  • zerr:ZDDY0023 if a map with the given name does not exist.

remove#2

declare %an:variadic %an:sequential function map:remove(
    $name as xs:QName,
    $key as xs:anyAtomicType?
) as empty-sequence() external

Removes an entry identified by the given key from the map. Note that it is possible to insert entries with empty key attributes. However as the removing the entries is based on the "eq" comparison and as "eq" with an empty sequence always return false, it is not possible to remove these entries.

Parameters

  • $name as xs:QName
    the name of the map
  • $key as xs:anyAtomicType

Returns

  • empty-sequence()

    the function is sequential and immediately removes the entry into the map but returns the empty-sequence.

Errors

  • zerr:ZDDY0023 if a map with the given name does not exist.
  • zerr:ZDDY0025 if the given number of key attributes does not match the number of key attributes specified when creating the map (see the map:create function).
  • zerr:ZXQD0005 if any of the given key attributes can not be cast (or is not a subtype) of the corresponding key attribute specified when creating the map.

See also

map:create

size#1

declare function map:size(
    $name as xs:QName
) as xs:integer external

The number of entries in a map. The following condition always holds: map:size($name) eq fn:count(map:keys($name))

Parameters

  • $name as xs:QName
    the name of the map

Returns

  • xs:integer

    the number of entries in the map.

Errors

  • zerr:ZDDY0023 if a map with the given name does not exist.
blog comments powered by Disqus