http://zorba.io/modules/unordered-maps

Description

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

import module namespace map = "http://zorba.io/modules/unordered-maps";
This module defines a set of functions for working with maps. A map is identified by a string and can be created using the map:create function and dropped using the map:drop function.

It is possible to create persistent and transient maps. The lifetime of a transient map is limited by the execution of the current query. A persistent map lives until it is explicitly dropped. Accordingly, it is also available to other requests.

For example, 
map:create("my-map", ["string", "integer"], { "persistent" : false })
will create a transient map named my-map having two keys. The types of the keys are string and integer.

The key of a particular entry in the map can consist of a tuple of atomic values (called key attributes). The actual type of each attribute is determined when the map is created. The value of each entry is a sequence of items. If an item in this sequence is a object or array, this item needs to belong to a collection, otherwise, an error is raised.

Module code

Here is the actual XQuery module code.

Authors

Matthias Brantner

Version Declaration

jsoniq version "1.0" encoding "utf-8";

Namespaces

anhttp://zorba.io/annotations
maphttp://zorba.io/modules/unordered-maps
verhttp://zorba.io/options/versioning
zerrhttp://zorba.io/errors

Variables

map:PERSISTENT as string

Constant containing the field name of the options object indiciating whether a map is persistent or transient.

Function Summary

create($name as string, $key-types as item()) as empty-sequence() external

Create a persistent map with a given name and type identifiers for the key attributes.

create($name as string, $key-types as item(), $options as object()) as empty-sequence() external

Create a map with a given name, type identifiers for the key attributes, and options.

drop($name as string) as empty-sequence() external

Deletes the map with the given name.

insert($name as string, $key as item(), $value as item()*) as empty-sequence() external

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

get($name as string, $key as item()) as item()* external

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

delete($name as string, $key as item()) as empty-sequence() external

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

keys($name as string) as array()* external

Returns the keys of all entries of a map.

size($name as string) as integer external

Returns the number of entries in a map.

available-maps() as string* external

The function returns a sequence of names of the maps that are available (persistent and non-persistent).

options($name as string) as object() external

The function returns the options that were passed during creation or the default options if no options were passed.

Functions

create#2

declare %an:sequential function map:create(
    $name as string,
    $key-types as item()
) as empty-sequence() external
Create a persistent map with a given name and type identifiers for the key attributes.

If the map has only one key attribute, a single type identifier is given, for more than one key attribute an array of type identifiers is given. Calling this function is equivalent to calling create with the options { "persistent" : true } Note that the function is sequential and immediately creates the map.

Each key-type should be specified as string (e.g. "integer", "string", "boolean", "double", or "datetime").

For example, 
map:create("my-map", "string")
or 
map:create("my-map", ["string", "integer"])
.

Parameters

  • $name

    the name of the map (the restrictions on collection names apply)

  • $key-type

    one type identifier or an array of type identifiers for the key attributes

Returns

  • empty-sequence()

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

Errors

  • err:XPTY0004

    if any of the key attribute types is not a subtype of anyAtomicType.

  • zerr:ZSTR0001

    if a map with the given name already exists.

  • zerr:ZDDY1000

    if the given name is not a legal collection name

  • zerr:ZDDY0043

    if any of the given options has an invalid type

create#3

declare %an:sequential function map:create(
    $name as string,
    $key-types as item(),
    $options as object()
) as empty-sequence() external
Create a map with a given name, type identifiers for the key attributes, and options.

If the map has only one key attribute, a single type identifier is given, for more than one key attribute an array of type identifiers is given. Currently only one option is supported: To create a transient map the object { "persistent" : false } has to be passed to the $options parameter. Note that the function is sequential and immediately creates the map in the store.

Note that a map cannot be created if it already exists in a parent context. For example, a map that was created in an outer query cannot be created again in an inner query executed using the reflection:eval-s function.

Parameters

  • $name

    the name of the map (the restrictions on collection names apply)

  • $key-type

    one type identifier or an array of type identifiers for the key attributes

  • $options

    an object describing options for the map

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 anyAtomicType.

  • zerr:ZSTR0001

    if a map with the given name already exists.

  • zerr:ZDDY1000

    if the given name is not a legal collection name

  • zerr:ZDDY0043

    if any of the given options has an invalid type

drop#1

declare %an:sequential function map:drop(
    $name as string
) as empty-sequence() external
Deletes the map with the given name.

Note that a map can only be dropped in the context it was created. For example, a map that was created in an outer query cannot be dropped in an inner query executed using the reflection:eval-s function.

Parameters

  • $name

    the name of the map to drop

Returns

  • empty-sequence()

    the function is sequential and immediately drops the map. It returns the empty-sequence.

Errors

  • zerr:ZDDY0023

    if a map with the given name does not exist.

insert#3

declare %an:sequential function map:insert(
    $name as string,
    $key as item(),
    $value as item()*
) as empty-sequence() external
Inserts a new entry into the map with the given name.

If the map has only one key attribute, a single key value is given, for more than one key attribute an array of key values is given. 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.

If an item in the value sequence is an object or array, this item needs to belong to a collection, otherwise, an an error is raised.

Note that it is possible to insert entries with empty key attributes or key attributes having the value null. However, as the comparison with an empty sequence or null always returns false, it is not possible to retrieve these entries.

For example, 
map:insert("my-map", "key", "value")
or 
map:insert("my-map", [ "key1", "key2" ] , (42, "value"))
.

Parameters

  • $name

    the name of the map

  • $key

    either a single attribute key or an array of keys

  • $value

    the value of the entry to insert

Returns

  • empty-sequence()

    the function is sequential and immediately inserts the entry into the map. It 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.

  • zerr:ZDDY1003

    if the value to insert is an object or array it must belong to a collection.

get#2

declare function map:get(
    $name as string,
    $key as item()
) as item()* external
Returns the value of the entry with the given key from the map.

If the map has only one key attribute, a single key value is given, for more than one key attribute an array of key values is given.

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.

For example, 
map:get("my-map", "key")
or 
map:get("my-map", [ "key1", "key2" ])
.

Parameters

  • $name

    the name of the map

  • $key

    either a single attribute key or an array of keys

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.

delete#2

declare %an:sequential function map:delete(
    $name as string,
    $key as item()
) as empty-sequence() external
Removes an entry identified by the given key from the map.

If the map has only one key attribute, a single key value is given, for more than one key attribute an array of key values is given.

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 delete these entries.

Parameters

  • $name

    the name of the map

  • $key

    either a single attribute key or an array of keys

Returns

  • empty-sequence()

    the function is sequential and immediately deletes 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.

keys#1

declare function map:keys(
    $name as string
) as array()* external
Returns the keys of all entries of a map. The keys are returned as sequence of arrays.

The following condition always holds: map:size($name) eq count(map:keys($name))

Parameters

  • $name

    the name of the map

Returns

  • array()*

    an sequence of arrays each array containing the values of all attributes of one key.

Errors

  • zerr:ZDDY0023

    if a map with the given name does not exist.

size#1

declare function map:size(
    $name as string
) as integer external
Returns the number of entries in a map.

The following condition always holds: map:size($name) eq count(map:keys($name))

Parameters

  • $name

    the name of the map

Returns

  • integer

    the number of entries in the map.

Errors

  • zerr:ZDDY0023

    if a map with the given name does not exist.

available-maps#0

declare function map:available-maps() as string* external
The function returns a sequence of names of the maps that are available (persistent and non-persistent). The sequence will be empty if there are no maps.

Returns

  • string*

    A sequence of string, one for each available map, or an empty sequence.

options#1

declare function map:options(
    $name as string
) as object() external

The function returns the options that were passed during creation or the default options if no options were passed.

Parameters

  • $name

    the name of the map

Returns

  • object()

    an options object

Errors

  • zerr:ZDDY0023

    if a map with the given name does not exist.