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

View as XML or JSON.

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.

Function Summary

available-maps () as string* external

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

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.

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

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

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

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

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.

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

Returns the keys of all entries of a 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.

size ($name as string) as integer external

Returns the number of entries in a map.

Variable Summary

Functions

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.

Parameters

Returns

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

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 as string
the name of the map (the restrictions on collection names apply)
key-types as item()

Returns

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

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 as string
the name of the map (the restrictions on collection names apply)
key-types as item()
options as object()
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.

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 as string
the name of the map
key as item()
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.

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 as string
the name of the map to drop

Returns

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

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 as string
the name of the map
key as item()
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.

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 as string
the name of the map
key as item()
either a single attribute key or an array of keys
value as item()
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.

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 as string
the name of the map

Returns

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

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 as string
the name of the map

Returns

object()
an options object

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 as string
the name of the map

Returns

integer
the number of entries in the map.

Variables

$map:PERSISTENT as string
Constant containing the field name of the options object indiciating whether a map is persistent or transient.