Standard Library: Map

std.map is an insertion-ordered map with i64 keys andi64 values, built on parallel keys/vals arrays. Iteration order MUST be insertion order — this is normative for determinism, and matches the contract from mind-spec/spec/v1.0/stdlib.md. The surface is a set of free functions (map_new(), map_insert(m, k, v), …) — MIND has no generic-type syntax yet, so there is no map<K,V> instantiation. The map<K,V>.new() form, where it parses, is pure syntactic sugar that desugars to these same i64/i64 free functions.

Availability: ships with mindc 0.4.2+ behind the std-surface feature flag (the shipped default since v0.7.1, still the default in the current v0.10.x line).

Layout

  • Struct: four i64 fields — keys_addr, vals_addr, len, cap.
  • Stride: 8 bytes per slot in each array.
  • Order: normative insertion order (no hashing, no balancing).
  • Lookup: linear scan of the keys array; O(n).

Public API

The functions below are the ones the reference std/map.mind actually ships today. Lookup (map_get / map_contains_key) is a linear scan in insertion order; map_insert is append-only (no in-place update of an existing key yet); map_get returns 0 when the key is absent rather than an Option. In-place key update and bucket hashing land later (the parallel insertion-order layout is already shaped for a side bucket-index array).

  • map_new() -> Map — empty map, zero allocation.
  • map_insert(m: Map, k: i64, v: i64) -> Map — append (k, v) at the tail; returns a fresh Map (non-mutating).
  • map_get(m: Map, k: i64) -> i64 — first value whose key == k (i64 identity), or 0 if absent.
  • map_contains_key(m: Map, k: i64) -> i64 — 1 if some key == k, else 0.
  • map_len(m: Map) -> i64 — current entry count.
  • map_cap(m: Map) -> i64 — backing-store capacity in entries.
  • map_key_at(m: Map, i: i64) -> i64 / map_value_at(m: Map, i: i64) -> i64 — load the key/value at logical index i (insertion order; no bounds check).
  • map_keys_addr(m: Map) -> i64 / map_vals_addr(m: Map) -> i64 — opaque i64 base addresses of the two backing arrays.
  • map_get_str(m: Map, k: i64) -> i64 / map_contains_key_str(m: Map, k: i64) -> i64 — String-key variants that compare key byte contents (not handle identity); use these for string keys.
Spec-planned, not yet shipped: mind-spec/spec/v1.0/stdlib.md also lists map_remove, map_contains, map_capacity, and map_free as part of the normative surface. These are not in the reference std/map.mind yet — the shipped count/capacity accessors are named map_len / map_cap, and membership is map_contains_key. Removal and explicit-free are tracked but not yet implemented.

Example

use std.map;

fn main() -> i64 {
    let m = map_new();
    let m = map_insert(m, 1, 100);
    let m = map_insert(m, 2, 200);
    let m = map_insert(m, 3, 300);

    let v = map_get(m, 2);             // 200
    let n = map_len(m);                // 3
    let has = map_contains_key(m, 9);  // 0 (absent)

    return v;
}

Forking the order semantics (Phase D)

Insertion order is normative in the bundled std.map. A deployment that wants a different iteration policy — e.g. sort-on-insert for a test-fixture canonicalizer — can ship its own map.mind and point MIND_STDLIB_PATH=path at it; the project loader swaps the bundled blob in without recompiling mindc. Shipped in v0.4.3 (RFC 0005 Phase D₁); see std.vecfor the full override contract.