Guide Manual Packages Playground

@std/collections

API Reference

class Map

Insertion-ordered hash table from keys to values. Build one with new Map<K, V>(), fill it with set, and read it back with get or has. A missing key reads as null rather than aborting, so ?? and ?. supply defaults.

Entries keep insertion order: setting an existing key keeps its slot, and deleting a key then setting it again appends it at the end. The deinit block frees the table and drops the map's reference to every key and value it still holds.

Keys must be Int, Float, Bool, String, or a heap object compared by identity; see the module notes for the full key rules. Printing a map renders {k: v, ...} in insertion order through the @std/io pretty renderer, so read the contents with keys() or values() when you need the pieces as values instead.

init()

fields

  • handle: Int
fn clear()

Drop every entry at once, releasing the map's reference to each key and value. The map stays usable, and later entries start a fresh insertion order.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("a", 1);
m.set("b", 2);
m.clear();
print(m.len(), m.keys().join(","));
Run in Playground
fn delete(key: K): Bool

Remove the entry for key and drop the map's reference to that key and value. The remaining keys keep their order, and a key set again later is appended at the end rather than returning to its old slot.

key — entry key.

returns — true when an entry was removed, false when key had none.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("a", 1);
m.set("b", 2);
print(m.delete("a"), m.len());
print(m.delete("a"));
print(m.keys().join(","));
Run in Playground
fn get(key: K): V?

Read the value stored under key.

A missing key reads as null instead of aborting, which means a null you stored yourself looks the same as an absent key. Use has to tell them apart, or ?? and ?. to pick a default.

key — entry key.

returns — the stored value, or `null` when key has no entry.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("ore", 7);
print(m.get("ore") ?? 0);
print(m.get("coal") ?? 0);
Run in Playground
fn has(key: K): Bool

Test whether key currently has an entry. An entry holding null still counts as present, which is the one case get cannot report.

key — entry key.

returns — true when key is present, false when it is absent.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("ore", 7);
print(m.has("ore"), m.has("coal"));
Run in Playground
fn iterator(): Iterator<K>

Fresh iterator over the keys in insertion order. This is what for..in calls, and every call restarts at the first key; next() yields null once the keys run out.

returns — an iterator over the keys.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("iron", 12);
m.set("coal", 7);
for name in m {
print(name, m.get(name) ?? 0);
}
Run in Playground
fn keys(): Array<K>

Snapshot of every key in insertion order, aligned index by index with values(). Mutating the returned array does not touch the map.

returns — a new key array; empty when the map is empty.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("iron", 12);
m.set("coal", 7);
m.set("iron", 14);
print(m.keys().join(", "));
print(m.len());
Run in Playground
fn len(): Int

Number of live entries. Overwriting a key does not change it, and a deleted key stops counting right away.

returns — entry count; 0 for an empty map.

fn set(key: K, val: V)

Store val under key. An existing entry for key is overwritten: the key keeps its position in insertion order, the old value's reference is dropped, and len() does not change. A key that was deleted earlier is a new entry and lands at the end.

The map takes a reference to val and keeps it until the entry is overwritten, deleted, or cleared. Nothing is returned, so calls cannot be chained.

key — entry key; must be `Int`, `Float`, `Bool`, `String`, or a heap object compared by identity.

val — value to store.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("a", 1);
m.set("b", 2);
m.set("a", 10);
print(m.keys().join(","));
print(m.values().join(","));
Run in Playground
fn values(): Array<V>

Snapshot of every value in key insertion order, aligned index by index with keys(). Mutating the returned array does not touch the map.

returns — a new value array; empty when the map is empty.

import { Map } from "@std/collections";

let m = new Map<String, Int>();
m.set("iron", 12);
m.set("coal", 7);
print(m.values().join(", "));
Run in Playground
class Set

Distinct members backed by a Map<T, Bool>, so members follow the same rules as Map keys: only hashable types, kept by reference count, handed back in insertion order. Adding a member that is already there keeps one copy and leaves its position alone. values() is the member list, since the member is the key.

The table lock makes a set shareable between threads; guard a check-then-add pair with a Mutex from @std/sync when threads race. The deinit block frees the backing map.

init()

fields

  • inner: Map<T, Bool>
fn add(val: T)

Add val as a member. A member that is already present is left untouched, so the length does not change and its position in insertion order stays where it was. A member that was deleted earlier is added again at the end.

The set takes a reference to val and keeps it until the member is deleted or the set is cleared. Nothing is returned, so calls cannot be chained.

val — member value; must be a hashable type.

import { Set } from "@std/collections";

let s = new Set<String>();
s.add("ore");
s.add("ore");
print(s.has("ore"), s.len());
print(s.values().join(", "));
Run in Playground
fn clear()

Drop every member at once, releasing the set's reference to each one. The set stays usable and later members start a fresh insertion order.

import { Set } from "@std/collections";

let s = new Set<String>();
s.add("ore");
s.add("coal");
s.clear();
print(s.len(), s.values().join(","));
Run in Playground
fn delete(val: T): Bool

Remove a member and drop the set's reference to it. The remaining members keep their order, and a member added again later lands at the end.

val — member value.

returns — true when a member was removed, false when val was absent.

import { Set } from "@std/collections";

let s = new Set<String>();
s.add("ore");
s.add("coal");
print(s.delete("ore"), s.len());
print(s.values().join(", "));
Run in Playground
fn has(val: T): Bool

Test whether val is currently a member.

val — member value.

returns — true when val is present, false when it is not.

import { Set } from "@std/collections";

let s = new Set<String>();
s.add("ore");
print(s.has("ore"), s.has("coal"));
Run in Playground
fn iterator(): Iterator<T>

Fresh iterator over the members in insertion order. This is what for..in calls, and every call restarts at the first member; next() yields null once the members run out.

returns — an iterator over the members.

import { Set } from "@std/collections";

let s = new Set<String>();
s.add("iron");
s.add("coal");
for member in s {
print(member);
}
Run in Playground
fn len(): Int

Number of distinct members.

returns — member count; 0 for an empty set.

fn values(): Array<T>

Snapshot of every member in insertion order. Mutating the returned array does not touch the set.

returns — a new member array; empty when the set is empty.

import { Set } from "@std/collections";

let s = new Set<String>();
s.add("iron");
s.add("coal");
print(s.values().join(", "));
Run in Playground