collections.hashmap

let mut m = HashMap[str, int].new()
m.insert("alice", 1)
m.insert("bob", 2)
assert(m.get("alice") == Some(1))
assert(m.len() == 2)

for (k, v) in m.iter() {
    assert(v > 0)
}

type HashMap[K Hashable, V] { ... }

type Hashable protocol {
    fn hash() -> u64
}

new

stable since 0.1

fn HashMap.new() -> HashMap[K, V]

Create an empty HashMap with an initial capacity of 16.

Examples

let mut m = HashMap[str, int].new()
assert(m.is_empty())

with_capacity

stable since 0.1

fn HashMap.with_capacity(min_capacity int) -> HashMap[K, V]

Create an empty HashMap sized to hold at least min_capacity entries without a rehash. The argument is an entry count, not a bucket count. Use this when the final size is known in advance.

Examples

let mut m = HashMap[str, int].with_capacity(100)
for i in 0..100 { m.insert("k" + str.from(i), i) }
assert(m.len() == 100)

from

stable since 0.1

fn HashMap.from(pairs [](K, V)) -> Self

Build a HashMap from an array of (key, value) pairs. Duplicate keys: last write wins.

Examples

let m = HashMap[str, int].from([("a", 1), ("b", 2)])
assert(m.get("a") == Some(1))
assert(m.len() == 2)

get

stable since 0.1

fn HashMap @get(key K) -> Option[V]

Look up key. Returns Some(value) if found, None otherwise.

Examples

let mut m = HashMap[str, int].new()
m.insert("x", 10)
assert(m.get("x") == Some(10))
assert(m.get("y") == None)

contains

stable since 0.1

fn HashMap @contains(key K) -> bool

Check whether key exists without retrieving the value. Equivalent to m.get(key) != None but avoids constructing the Option.

get_or_insert

stable since 0.1

fn HashMap mut @get_or_insert(key K, fallback fn() -> V) -> V

Return the value for key if it exists. Otherwise call fallback(), insert the result, and return it. The fallback is lazy — it is only called on a cache miss.

Examples

let mut counts = HashMap[str, int].new()
let prev = counts.get_or_insert("foo", || 0)
counts.insert("foo", prev + 1)
assert(counts.get("foo") == Some(1))

insert

stable since 0.1

fn HashMap mut @insert(key K, value V) -> Option[V]

Insert (key, value). If the key already exists, overwrites it and returns Some(old_value). Otherwise inserts and returns None. May trigger a rehash.

Examples

let mut m = HashMap[str, int].new()
assert(m.insert("a", 1) == None)
assert(m.insert("a", 2) == Some(1))
assert(m.get("a") == Some(2))

remove

stable since 0.1

fn HashMap mut @remove(key K) -> Option[V]

Delete the entry for key. Returns Some(old_value) if the key existed, None otherwise. Leaves a tombstone slot — the internal array does not shrink.

Examples

let mut m = HashMap[str, int].from([("a", 1)])
assert(m.remove("a") == Some(1))
assert(m.remove("a") == None)

clear

stable since 0.1

fn HashMap mut @clear() -> ()

Remove all entries. The internal bucket array is retained (capacity is preserved), so re-inserting elements does not require immediate reallocation.

merge_from

stable since 0.1

fn HashMap mut @merge_from(other HashMap[K, V]) -> ()

Merge all entries from other into self. Override semantics: existing keys are overwritten.

Examples

let mut a = HashMap[str, int].from([("x", 1)])
let b = HashMap[str, int].from([("x", 99), ("y", 2)])
a.merge_from(b)
assert(a.get("x") == Some(99))
assert(a.get("y") == Some(2))

len

stable since 0.1

fn HashMap @len() -> int

Number of live entries (does not count tombstone slots left by remove).

is_empty

stable since 0.1

fn HashMap @is_empty() -> bool

Returns true when len() == 0.

capacity

stable since 0.1

fn HashMap @capacity() -> int

Total size of the internal bucket array. Always ≥ len(). Use with_capacity to control this at construction time.

iter

stable since 0.1

fn HashMap @iter() -> HashMapIter[K, V]

Iterator over (key, value) pairs in unspecified order.

Examples

let m = HashMap[str, int].from([("a", 1), ("b", 2)])
for (k, v) in m.iter() {
    assert(v > 0)
}

keys

stable since 0.1

fn HashMap @keys() -> KeysIter[K, V]

Iterator over keys only, in unspecified order.

values

stable since 0.1

fn HashMap @values() -> ValuesIter[K, V]

Iterator over values only, in unspecified order.

filter

stable since 0.1

fn HashMap @filter(pred fn(K, V) -> bool) -> HashMap[K, V]

Return a new HashMap containing only the pairs for which pred(k, v) is true. Does not mutate the original.

Examples

let m = HashMap[str, int].from([("a", 1), ("b", 2), ("c", 3)])
let big = m.filter(|_, v| v > 1)
assert(big.len() == 2)

clone

stable since 0.1

fn HashMap @clone() -> HashMap[K, V]

Create an independent deep copy of the map. Mutations to the clone do not affect the original.

Examples

let m = HashMap[str, int].from([("a", 1)])
let m2 = m.clone()
assert(m2.get("a") == Some(1))