MIND/Docs/Standard library
Home

Product

FeaturesUse CasesLanguage ProfilesEcosystemShowcaseBenchmarksCompareRoadmap

Enterprise

OverviewCompliancePilot ProgramPricingSecurityAdoption Flow
Community
Get started

Standard Library: Map

std.map is an insertion-ordered map with i64 keys and i64 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.

Warning

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

Map (heap record)

  1. keys_addri64
  2. vals_addri64
  3. leni64
  4. capi64

keys_addr points to slots of 8 bytes

  1. +0
  2. +8
  3. +16
  4. +24
  5. +32
  6. …

vals_addr points to slots of 8 bytes

  1. +0
  2. +8
  3. +16
  4. +24
  5. +32
  6. …
Four i64 fields over two parallel arrays; entry i is keys[i] with vals[i], in insertion order.

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 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() -> MapEmpty map, zero allocation.
  • map_insert(m: Map, k: i64, v: i64) -> MapAppend (k, v) at the tail; returns a fresh Map (non-mutating).
  • map_get(m: Map, k: i64) -> i64First value whose key == k (i64 identity), or 0 if absent.
  • map_contains_key(m: Map, k: i64) -> i641 if some key == k, else 0.
  • map_len(m: Map) -> i64Current entry count.
  • map_cap(m: Map) -> i64Backing-store capacity in entries.
  • map_key_at(m: Map, i: i64) -> i64 / map_value_at(m: Map, i: i64) -> i64Load the key/value at logical index i (insertion order; no bounds check).
  • map_keys_addr(m: Map) -> i64 / map_vals_addr(m: Map) -> i64Opaque i64 base addresses of the two backing arrays.
  • map_get_str(m: Map, k: i64) -> i64 / map_contains_key_str(m: Map, k: i64) -> i64String-key variants that compare key byte contents (not handle identity); use these for string keys.

Warning

Spec-planned, not yet shipped: the stdlib spec also lists map_remove, map_contains, map_capacity, and map_free as part of the normative surface. These are not in the reference 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.vec for the full override contract.

On this page