Maps | Atoll Book

Map[K, V] is a hash map. Lookup and mutation require K: Hashable.

mut ports: Map[string, int] = Map.new()
ports.put("http", 80)
ports.put("https", 443)

Map.new[K, V](capacity) creates an empty map with an optional capacity hint. Map.copy(other, capacity) creates an independent map. Capacity affects allocation only; it does not insert entries.

Equal keys must produce equal hash codes. Derive or implement Equatable and Hashable together.

Lookup

get(key) returns V?:

port := ports.get("https").unwrap_or(443)

get_or_default takes an eager fallback; get_or_else computes one lazily. contains_key tests keys, and contains_value requires equatable values.

port := ports.get_or_else("admin", () => load_admin_port())

Use get plus match when missing and present cases need different side effects. Use the fallback helpers only when absence is fully handled by a replacement value.

Mutation

put inserts or replaces. remove returns the removed V?. clear empties the map.

match ports.remove("http") {
    Some(old) => log_removed(old)
    None => {}
}

These methods require a mutable receiver binding. Immutable-style plus, plus_all, minus, and merge return a new map.

merge(other, resolve) invokes the resolver for duplicate keys and copies non-conflicting entries. Inserting a key equal to an existing key replaces its value; the size does not increase.

Views

keys() returns Set[K], values() returns []V, and entries() returns a set of (K, V) tuples. Dedicated entry, key, and value iterators avoid building those full views when streaming traversal is enough.

for key, value in ports {
    println("$key: $value")
}

Map iteration yields (K, V).

keys, values, and entries allocate complete collections. Use iter_keys, iter_values, or iter_entries for one-pass traversal without materializing a view. Hash-map iteration order is unspecified and must not drive serialized or user-visible ordering.

Transformation

Operation	Result
`map(f)`	List with one output per entry
`map_keys(f)`	Map with transformed keys
`map_values(f)`	Map with transformed values
`filter`, `filter_keys`, `filter_values`	Map containing matching entries
`flat_map(f)`	Concatenated list outputs
`reduce(initial, f)`	One accumulated value
`find(f)`	First matching `(K, V)?` in iteration order

When map_keys produces duplicate keys, later insertions replace earlier values under ordinary map semantics.

Predicate methods any, all, and none short-circuit. count visits every entry. to_list() materializes entry tuples, but preserves no stable ordering.

Sorted maps

SortedMap[K, V] is the ordered-map contract. It adds first/last key and entry, head/tail/sub-map ranges, and floor/ceiling lookup:

Method	Meaning
`first_key`, `last_key`	Boundary key or `None`
`first_entry`, `last_entry`	Boundary entry or `None`
`head_map`, `tail_map`, `sub_map`	Ordered range
`floor_key`	Greatest key less than or equal to the target
`ceiling_key`	Least key greater than or equal to the target

The installed sorted surface is less deeply runtime-backed than the primary hash-map implementation. Treat it as provisional and retain an end-to-end test when using it; prefer Map plus explicit sorting for stable deployed behavior today.

Key contracts

Do not mutate fields that participate in a key’s equality or hash while the key is stored. Doing so can make an existing entry unreachable by lookup. Immutable value types make the safest keys.

Map equality is entry-based rather than iteration-order-based. Hashing folds entries in an order-independent way so equivalent maps remain compatible as fields of derived hashable values.