API Reference

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(","));

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(","));

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);

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"));

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);
}

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());

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(","));

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(", "));

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(", "));

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(","));

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(", "));

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"));

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);
}

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(", "));