Collections & text

Dictionaries

dict[K:V] is pure syntax sugar over the standard-library Map[K, V] class: the literal and the dict[K:V] type desugar to Map, and a dict value is a Map — there is one type and one API (get, put, keys, del, …). Use the dict syntax for the convenient literal; everything else is the Map class.

Creating Dictionaries

dict[int:str] map = new dict[int:str]{
    1: "one",
    2: "two",
    3: "three"
}

Accessing Elements

dict[int:str] d = new dict[int:str]{
    1: "a",
    2: "b"
}

str value = d[1]  # "a"
d[3] = "c"  # Add/change

Missing Keys

Reading a key that was never set raises an Error with kind ERR_BOUNDS — a key the dict does not hold is out of range the same way a[9] is on a two-element array. Writing a new key is always fine; it is only reading that requires the key to be there.

dict[str:int] counts = new dict[str:int]{}

counts["ada"]                                 # ERR_BOUNDS — never set
counts["ada"] = 1                             # fine: a write creates the key

Use the accessor that expects an absent key rather than catching the error:

counts.key(word)                              # bool — is it there?
counts.getOrDefault(word, 0)                  # the value, or a fallback
counts.get(word)                              # ptr[V] — null when absent

This matters most in the accumulate-into-a-dict shape, where the first sighting of a key would otherwise fail:

# not this — it raises the first time a word is seen
# counts[word] = counts[word] + 1

counts[word] = counts.getOrDefault(word, 0) + 1

Dictionary Methods

len — Number of Elements

int count = d.len

put(key, value) — Set Value

d.put(5, "e")

del(key) — Delete Element

bool deleted = d.del(2)  # true if element was deleted

key(key) — Check Key Existence

bool exists = d.key(5)  # true if key exists

val(value) — Check Value Existence

bool hasValue = d.val("c")  # true if value exists

keys — Array of Keys

array[int] allKeys = d.keys()

vals — Array of Values

array[str] allValues = d.vals()

arr — Array of Tuples (key, value)

array[tuple[int, str]] pairs = d.arr()

Because a dict is a Map, the rest of the Map API works on it too — get, getOrDefault, at, putIfAbsent, empty, clear, and more. See Standard Library → Map for the full list.