const func type: hash [ (in type: keyType) ] (in type: baseType)

Abstract data type, describing hash maps. A hash map stores key-value pairs. A hash map guarantees that a key can be mapped quickly to its corresponding value. The keys of a hash map have the type keyType and the value have the type baseType. A hash map is only possible, if keyType supports the functions hashCode and compare.

const func baseType: (in hashType: aHashMap) [ (in keyType: aKey) ]

Access one value from the hash table aHashMap.

Returns:

the element with the key aKey from aHashMap.

Raises:

INDEX_ERROR - If aHashMap does not have an element with the key aKey.

const func baseType: (in hashType: aHashMap) [ (in keyType: aKey) default (in baseType: defaultValue) ]

Access one value from the hash table aHashMap.

Returns:

the element with the key aKey from aHashMap or defaultValue if aHashMap does not have an element with the key aKey.

const func boolean: (in keyType: aKey) in (in hashType: aHashMap)

Hash membership test. Determine if aKey is a member of the hash map aHashMap.

Returns:

TRUE if aKey is a member of aHashMap, FALSE otherwise.

const func boolean: (in keyType: aKey) not in (in hashType: aHashMap)

Negated hash membership test. Determine if aKey is not a member of the hash map aHashMap.

Returns:

FALSE if aKey is a member of aHashMap, TRUE otherwise.

const proc: (inout hashType: aHashMap) @:= [ (in keyType: aKey) ] (in baseType: anElem)

Add anElem with the key aKey to the hash map aHashMap. If an element with the key aKey already exists, it is overwritten with anElem.

aHash @:= [aKey] aValue;

Raises:

MEMORY_ERROR - If there is not enough memory.

const func keyValueType: [ (in keyType: aKey) : (in baseType: aValue) ]

Create a key-value pair to be used in a hash literal. A key-value pair with the key "one" and the value 1 is created with

["one" : 1]

A key-value pair can only be used inside a hash literal. E.g.:

[] (["one" : 1], ["two" : 2])

This hash literal defines a hash with the keys "one" and "two" and the corresponding values 1 and 2.

const func hashType: [] (in func keyValueType: keyValuePairs)

Declare a hash literal from key-value pairs. One or many key-value pairs are used to create a hash literal:

[] (["one" : 1], ["two" : 2])

This hash literal defines a hash with the keys "one" and "two" and the corresponding values 1 and 2.

const func integer: length (in hashType: aHashMap)

Number of elements in the hash map aHashMap.

Returns:

the number of elements in aHashMap.

const proc: incl (inout hashType: aHashMap, in keyType: aKey, in baseType: anElem)

Add anElem with the key aKey to the hash map aHashMap. If an element with the key aKey already exists, it is overwritten with anElem.

incl(aHash, aKey, aValue);

Raises:

MEMORY_ERROR - If there is not enough memory.

const proc: excl (inout hashType: aHashMap, in keyType: aKey)

Remove the element with the key aKey from the hash map aHashMap.

const func baseType: update (inout hashType: aHashMap, in keyType: aKey, in baseType: anElem)

Add anElem with the key aKey to the hash map aHashMap. If an element with the key aKey already exists, it is overwritten with anElem and the old value is returned.

oldValue := update(aHash, aKey, newValue);

Parameters:

aHashMap - Hash map to be updated.

aKey - Key of the value to be updated.

anElem - Data value to be added to the hash map.

Returns:

the old element with the key aKey or anElem if no old element existed.

Raises:

MEMORY_ERROR - If there is not enough memory.

const proc: for (inout baseType: forVar) range (in hashType: aHashMap) do (in proc: statements) end for

For-loop where forVar loops over the values of the hash map aHashMap. The succession of values is unordered and not related to the order in which the values have been added to the hash map. E.g.:

for aValue range aHash do ...

In many cases it is okay to process the values unordered. The values can be processed in an ordered way by using values and sort:

for aValue range sort(values(aHash)) do ...

const proc: for key (inout keyType: keyVar) range (in hashType: aHashMap) do (in proc: statements) end for

For-loop where keyVar loops over the keys (indices) of the hash map aHashMap. The succession of keys (indices) is unordered and not related to the order in which the keys have been added to the hash map. E.g.:

for aKey range aHash do ...

In many cases it is okay to process the keys (indices) unordered. The keys can be processed in an ordered way by using keys and sort:

for aKey range sort(keys(aHash)) do ...

const proc: for (inout baseType: forVar) key (inout keyType: keyVar) range (in hashType: aHashMap) do (in proc: statements) end for

For-loop where forVar and keyVar loop over the hash map aHashMap. The variable forVar loops over the values of aHashMap and keyVar loops over the keys (indices) of aHashMap. The succession of keys (indices) and values is unordered and not related to the order in which they have been added to the hash map. E.g.:

for aValue key aKey range aHash do ...

In many cases it is okay to process the keys (indices) and values unordered. The keys and values can be processed in an ordered way by using keys and sort:

for aKey range sort(keys(aHash)) do
  value := aHash[aKey];
  ...

const func array keyType: keys (in hashType: aHashMap)

Obtain the keys of the hash map aHashMap. The returned array of keys is unordered and the succession of keys is not related to the order in which the keys have been added to the hash map. A loop over the keys like

for aKey range keys(aHash) do ...

is equal to the following for-each loop

for key aKey range aHash do ...

The keys can be processed in an ordered way by using sort:

for aKey range sort(keys(aHash)) do ...

Returns:

an unordered array with the keys of the hash map.

const func array baseType: values (in hashType: aHashMap)

Obtain the values of the hash map aHashMap. The returned array of values is unordered and the succession of values is not related to the order in which the values have been added to the hash map. A loop over the values like

for aValue range values(aHash) do ...

is equal to the following for-each loop

for aValue range aHash do ...

The values can be processed in an ordered way by using sort:

for aValue range sort(values(aHash)) do ...

Returns:

an unordered array with the values of the hash map.

const func hash [baseType] array keyType: flip (in hashType: aHashMap)

Create a hash map from aHashMap where key and value are exchanged. Since a hash value can correspond to many keys the type returned is hash [baseType] array keyType.

const type: stringIntegerHash is hash [string] integer;
const type: integerStringHash is hash [integer] array string;
...
var stringIntegerHash: aHash is [] (["zero" : 0], ["null" : 0], ["one" : 1]);
var integerStringHash: stringsByIntValue is integerStringHash.value;
var integer: number is 0;
var string: stri is "";
...
stringsByIntValue := flip(aHash);
for number range sort(keys(stringsByIntValue)) do
  for stri range stringsByIntValue[number] do
    writeln(stri <& ": " <& number);
  end for;
end for;