CLASS T.dict<Tkey, Titem> @public

summary

The builtin type dict.

A dict contains zero or more items of the item type specified in the declaration, looked up by a key.

The key can be a number, string, enum, bool, status or an object. In case of an object its identity is used, thus two different objects with the exactly the same value function as different keys.

Besides the object methods, Zimbu has these syntax items for dict:

 dict<string, int> dict = ["one": 1, "two": 2]  # dict initializer
 dict<string, int> dict = O["one": 1, "two": 2] # idem, with ordered keys
 string s = dict["one"]                         # get dict item by key
 intdict["nine"] = 9                            # set dict item by key
 dict<string, bool> another = [:]               # empty dict initializer

When getting an item by index with intdict[key] and the key does not exist this throws an exception.

When setting an item by key with intdict[key] = value and the key already exists the value is overwritten, just like with $set(). Use $add() to throw an exception for this situation.

Optionally the dict can be created ordered. It then uses a list to remember the order in which keys were added. ToString(), keys() and values() will then have the items in the order they were added. This has a small overhead. Without the list the order of items depends on the hash value and the number of items, which is rather arbitrary.

	NEW() @public	Create a new, empty dictionary.
	NEW(ordered) @public	Create a new, empty dictionary.
	$Size() int @public	Return the number of items in the dict.
	$isOrdered() bool @public	Return whether this dict keeps ordering of items.
	$copy() dict<Tkey, Titem> @public	Return a shallow copy of the dict.
	$ToString() string @public	Return a string representation of the dict.
	$ToString(format) string @public	Return a string representation of the dict with specified formatting.
	$Type() type @public	Return the type of the dict.
	$has(key) bool @public	Return TRUE when there is an item with key key.
	$get(key) Titem @public	Return the value of the item with key key.
	$get(key, default) Titem @public	Return the value of the item with key key.
	$getByIndex(idx) Titem @public	Return the value of the item at index idx.
	$getByIndex(idx, default) Titem @public	Return the value of the item at index idx.
	$add(key, value) dict<Tkey, Titem> @public	Set the value of the item with key key to value. Throws an exception when key is already present. Use $set() if that is not wanted.
	$set(key, value) dict<Tkey, Titem> @public	Set the value of the item with key key to value.
	$clear() dict<Tkey, Titem> @public	Removes all items from the dict.
	$clear(key) dict<Tkey, Titem> @public	Removes the item with key key and returns the dict.
	$remove(key) Titem @public	Removes the item with key key and returns the removed value.
	$keys() list<Tkey> @public	Returns a list with all the keys of the dict.
	$values() list<Titem> @public	Returns a list with all the values of the dict.
	$map(f) dict<Tkey, Titem> @public	Execute function f on each item value. Each item is replaced by the result of the function.
	$keyMap(f) dict<Tkey, Titem> @public	Execute function f on each item key and value. Each item is replaced by the result of the function.
	$mapTo(f) dict<Tkey, Tresult> @public	Create a new dict where each item is the result of executing function f on each item value of this dict.
	$keyMapTo(f) dict<Tkey, Tresult> @public	Create a new dict where each item is the result of executing function f on each item key and value of this dict.
	$forEach(f) dict<Tkey, Titem> @public	Call method f for every item value in the dict.
	$forKeyEach(f) dict<Tkey, Titem> @public	Call method f for every item key and value in the dict.

members (alphabetically)

PROC NEW() @public

Create a new, empty dictionary.

PROC NEW(bool ordered) @public

Create a new, empty dictionary.

When ordered is TRUE keep the order in which the items were added. values() and keys() return the items in that order.

FUNC $Size() int @public

Return the number of items in the dict.

When used on NIL Size() returns zero, it does not throw an E.NilAccess exception.

FUNC $ToString() string @public

Return a string representation of the dict.

Starts with "[" and ends in "]". Between the key and the item ": " is used. Key-item pairs are separated with ", ".

An empty dict returns "[:]".

 string s = ["a": 12, "b": 34].ToString()
 # s == "["a": 12, "b": 34]".

A NIL dict returns "NIL"

Each item is converted to a string by calling its ToString() method, if there is one.

The order of items is unpredictable, unless this is an ordered dict, then the items will be in the order they were added.

If the dict contains itself somehow, instead of recursing "[recursive-dict]" will be used. However, if multiple threads are doing this for the same dict the effect is unpredictable.

FUNC $ToString(string format) string @public

Return a string representation of the dict with specified formatting.

Currently works like ToString() without a format argument.

TODO: limit depth, limit number of items (like string truncation, optional ellipses), etc.

FUNC $Type() type @public

Return the type of the dict.

Invoking ToString() on the returned type results in something like "dict<string, int>".

FUNC $add(Tkey key, Titem value) dict<Tkey, Titem> @public

Set the value of the item with key key to value. Throws an exception when key is already present. Use $set() if that is not wanted.

Returns the dict.

FUNC $clear() dict<Tkey, Titem> @public

Removes all items from the dict.

Returns the dict.

FUNC $clear(Tkey key) dict<Tkey, Titem> @public

Removes the item with key key and returns the dict.

Throws an exception when key is not present in the dict.

Returns the dict. $remove(key) does the same but returns the value.

FUNC $copy() dict<Tkey, Titem> @public

Return a shallow copy of the dict.

FUNC $forEach(proc<Titem> f) dict<Tkey, Titem> @public

Call method f for every item value in the dict.

The argument for f is the value.

The order in which f is called for each item is undefined.

Returns the dict.

FUNC $forKeyEach(proc<Tkey, Titem> f) dict<Tkey, Titem> @public

Call method f for every item key and value in the dict.

The first argument for f is the key, the second argument is the value.

The order in which f is called for each item is undefined.

Returns the dict.

FUNC $get(Tkey key) Titem @public

Return the value of the item with key key.

Throws an exception when key is not present in the dict.

FUNC $get(Tkey key, Titem default) Titem @public

Return the value of the item with key key.

When key is not present in the dict returns default.

FUNC $getByIndex(int idx) Titem @public

Return the value of the item at index idx.

Throws an exception when the dict is not ordered and when idx is out of range.

FUNC $getByIndex(int idx, Titem default) Titem @public

Return the value of the item at index idx.

Returns default when the dict is not ordered or when idx is out of range.

FUNC $has(Tkey key) bool @public

Return TRUE when there is an item with key key.

FUNC $isOrdered() bool @public

Return whether this dict keeps ordering of items.

When the order in which items are added is remembered, values() and keys() return the items in that order.

FUNC $keyMap(func<Tkey, Titem => Titem> f) dict<Tkey, Titem> @public

Execute function f on each item key and value. Each item is replaced by the result of the function.

f has two arguments: The key and the value of the item. f must return the new value of the item.

 dict<int, string> d = [1: "a", 2: "b", 3: "c"]
 d.keyMap({ k, v => k .. "/" .. v })
 # d == [1: "1/a", 2: "2/b", 3: "3/c"]

Returns the dict.

FUNC $keyMapTo(func<Tkey, Titem => Tresult> f) dict<Tkey, Tresult> @public

Create a new dict where each item is the result of executing function f on each item key and value of this dict.

This is like keyMap() but with a different result type.

If this dict is ordered, the resulting dict will also be ordered, thus the order of keys remains the same

f has two arguments: The key in the dict and the value of the item. f must return the value for the new dict.

 dict<string, int> id = ["one": 11, "two": 22, "three": 33]
 dict<string, string> sd = id.keyMapTo({ k, n => k .. ": " .. n })
 # sd == ["one": "one: 11", "two": "two: 22", "three": "three: 33"]

Returns the dict.

FUNC $keys() list<Tkey> @public

Returns a list with all the keys of the dict.

The order is undefined, unless this is an ordered dict.

When the dict is NIL this returns NIL.

FUNC $map(func<Titem => Titem> f) dict<Tkey, Titem> @public

Execute function f on each item value. Each item is replaced by the result of the function.

f has one argument, which is the current value of the item, and must return the new value of the item.

 dict<int, string> d = [1: "a", 2: "b", 3: "c"]
 d.map({ s => s .. "+" })
 # d == [1: "a+", 2: "b+", 3: "c+"]

Returns the dict.

FUNC $mapTo(func<Titem => Tresult> f) dict<Tkey, Tresult> @public

Create a new dict where each item is the result of executing function f on each item value of this dict.

This is like map() but with a different result type.

If this dict is ordered, the resulting dict will also be ordered, thus the order of keys remains the same

f has one argument, which is the value of the item, and must return the value for the new dict.

 dict<string, int> id = ["one": 1, "two": 2, "three": 3]
 dict<string, string> sd = id.mapTo({ n => n .. ":" })
 # sd == ["one": "1:", "two": "2:", "three": "3:"]

Returns the new dict.

FUNC $remove(Tkey key) Titem @public

Removes the item with key key and returns the removed value.

Throws an exception when key is not present in the dict.

Returns the value of the removed item. $clear(key) does the same but returns the dict.

FUNC $set(Tkey key, Titem value) dict<Tkey, Titem> @public

Set the value of the item with key key to value.

When key is already present in the dict the value is replaced. Use $add() to disallow replacing.

Returns the dict.

FUNC $values() list<Titem> @public

Returns a list with all the values of the dict.

The order is undefined, unless this is an ordered dict.

When the dict is NIL this returns NIL.

license

Licensed under the Apache License, Version 2.0. See the LICENSE file or obtain a copy at: http://www.apache.org/licenses/LICENSE-2.0