(std mutable map)

Reference

Overview

In-place hash table backed directly by .NET Dictionary<K,V>.

(import (std mutable map))

;; Count occurrences of words:
(def counts (mutablemap))
(for-each (fun (w) (mutablemap-set! counts w (+ 1 (mutablemap-ref-or counts w 0))))
          (list "a" "b" "a"))
(mutablemap-ref counts "a")      ; 2
(mutablemap-try-ref counts "c")  ; None

(MutableMap k v) directly aliases .NET Dictionary<K,V>. Key lookups, insertions, and removals run in expected O(1) time. Foreign methods accepting Dictionary<K,V> accept MutableMap directly.

Mutability. Operations such as mutablemap-set! modify the table in place and return unit. Modifications are immediately visible to all holders of the map reference. Unlike TransientMap (which is frozen back into an immutable Map), a MutableMap remains mutable indefinitely. Suitable for long-lived caches, counters, and indices.

Key comparison. Keys are compared using .NET’s default equality comparer (EqualityComparer<K>.Default). For types defined in Bjolang, this resolves to the type’s Eq instance. Modifying keys while stored in the map leads to undefined lookup behavior.

Null key support. Standard .NET dictionaries reject null keys. Because empty union cases are represented as null in the runtime, Bjolang’s mutable maps maintain an optional slot for null keys beside the dictionary. Dictionaries instantiated outside this module lack this slot, and passing null keys to them raises System.ArgumentNullException.

Missing keys. mutablemap-ref raises System.Collections.Generic.KeyNotFoundException if a key is absent. Use mutablemap-try-ref or mutablemap-ref-or to avoid exceptions.

Iteration order. Maps are unordered; iteration order reflects internal bucket layout. If a null key is present, it is visited first.

Iteration safety. Iterating over keys, values, or entries (mutablemap->seq, mutablemap-keys, or cursor loops) reads the live dictionary directly. Modifying the map during iteration raises System.InvalidOperationException. To mutate during iteration, take a snapshot first via mutablemap->list.

Equality and hashing. Two maps are = if they contain identical keys and equal corresponding values. Because maps are mutable, eq-hash raises an exception to prevent using mutable maps as keys.

Thread safety. Mutable maps are not thread-safe. Concurrent mutations require external locking. For concurrent transactional access across fibers, see (std stm map).

Traits. Implements Refable with keys as indices, Iterable and Collection over (Tuple k v), Addable! of (Tuple k v) (replacing existing values), Eq, Written and Displayed.

See also: MutableMap, mutablemap, mutablemap-set!, mutablemap-ref, mutablemap-try-ref

Reference

Types

Functions

Types

MutableMap

type alias ↑ Types

In-place hash table mapping %k to %v (aliases .NET Dictionary<K,V>).

%k
The key type (compared with .NET equality).
%v
The value type.

See also: mutablemap, map->mutablemap, Map

MutableMapCursor

type alias ↑ Types

Stateful cursor for iterating over a MutableMap.

%k
The key type.
%v
The value type.

Wraps .NET’s dictionary enumerator struct inside an object reference to support cursor-based step iteration with zero allocations per entry.

See also: mutablemap-cursor, mutablemap-cursor-done?, mutablemap-cursor-current

Functions

mutablemap

function ↑ Functions

(: mutablemap (-> (MutableMap %k %v)))

Creates an empty mutable map.

returns
A new empty mutable map.

See also: mutablemap-with-capacity, list->mutablemap

mutablemap-with-capacity

function ↑ Functions

(: mutablemap-with-capacity (-> int (MutableMap %k %v)))

Creates an empty mutable map with preallocated bucket capacity.

capacity
Initial capacity before rehashing is required. Must be >= 0.
returns
A new empty mutable map.
raises System.ArgumentOutOfRangeException
When capacity is negative.

Preallocates internal hash buckets to avoid resizing overhead when the entry count is known in advance.

See also: mutablemap

mutablemap-length

function ↑ Functions

(: mutablemap-length (-> (MutableMap %k %v) int))

Returns the number of entries in the map.

m
The map.
returns
The count of key-value pairs.

See also: mutablemap-empty?

mutablemap-empty?

function ↑ Functions

(: mutablemap-empty? (-> (MutableMap %k %v) bool))

Tests if the map contains no entries.

m
The map.
returns
#t if empty, otherwise #f.

See also: mutablemap-length

mutablemap-ref

function ↑ Functions

(: mutablemap-ref (-> (MutableMap %k %v) %k %v))

Returns the value associated with a key, raising KeyNotFoundException if missing.

m
The map.
k
The key to look up.
returns
The value associated with k.
raises System.Collections.Generic.KeyNotFoundException
When k is not in the map.

See also: mutablemap-try-ref, mutablemap-ref-or, ref

mutablemap-try-ref

function ↑ Functions

(: mutablemap-try-ref (-> (MutableMap %k %v) %k (out %v) (Option %v)))

Returns (Some value) for a key, or None if absent.

m
The map.
k
The key to look up.
returns
(Some v) if k is present, otherwise None.

See also: mutablemap-ref, mutablemap-ref-or, try-ref

mutablemap-ref-or

function ↑ Functions

(: mutablemap-ref-or (-> (MutableMap %k %v) %k %v %v))

Returns the value for a key, or a default fallback if absent.

m
The map.
k
The key to look up.
default
Fallback value returned if k is absent.
returns
The value associated with k, or default.

See also: mutablemap-ref, mutablemap-try-ref

mutablemap-set!

function ↑ Functions

(: mutablemap-set! (-> (MutableMap %k %v) %k %v void))

Associates a key with a value, overwriting any existing value.

m
The map to modify.
k
The key.
v
The value to associate with k.
raises System.ArgumentNullException
When k is null and m is an external .NET Dictionary.

See also: mutablemap-add!, mutablemap-remove!

mutablemap-add!

function ↑ Functions

(: mutablemap-add! (-> (MutableMap %k %v) %k %v bool))

Adds a key-value entry only if the key is not already present.

m
The map to modify.
k
The key.
v
The value to associate with k.
returns
#t if the key was new and inserted, #f if the key already existed.
raises System.ArgumentNullException
When k is null and m is an external .NET Dictionary.

Checks presence and inserts in a single dictionary operation.

See also: mutablemap-set!

mutablemap-remove!

function ↑ Functions

(: mutablemap-remove! (-> (MutableMap %k %v) %k bool))

Removes a key and its associated value from the map.

m
The map to modify.
k
The key to remove.
returns
#t if the key was present and removed, #f otherwise.

See also: mutablemap-set!, mutablemap-clear!

mutablemap-clear!

function ↑ Functions

(: mutablemap-clear! (-> (MutableMap %k %v) void))

Removes all entries from the map.

m
The map to clear.

See also: mutablemap-remove!

mutablemap-contains?

function ↑ Functions

(: mutablemap-contains? (-> (MutableMap %k %v) %k bool))

Tests if a key exists in the map.

m
The map.
k
The key to locate.
returns
#t if k is present, otherwise #f.

See also: mutablemap-try-ref

mutablemap-keys

function ↑ Functions

(: mutablemap-keys (-> (MutableMap %k %v) (Seq %k)))

Returns a sequence of all keys in the map.

m
The source map.
returns
A Seq iterating over m's keys.

Views the live map. Mutating the map during sequence traversal raises System.InvalidOperationException.

See also: mutablemap-values, mutablemap->seq

mutablemap-values

function ↑ Functions

(: mutablemap-values (-> (MutableMap %k %v) (Seq %v)))

Returns a sequence of all values in the map.

m
The source map.
returns
A Seq iterating over m's values in key order.

Views the live map. Mutating the map during sequence traversal raises System.InvalidOperationException.

See also: mutablemap-keys, mutablemap->seq

mutablemap-copy

function ↑ Functions

(: mutablemap-copy (-> (MutableMap %k %v) (MutableMap %k %v)))

Creates a shallow copy of the map.

m
The map to copy.
returns
A new mutable map with identical entries. Keys and values are not cloned.

See also: mutablemap->map

mutablemap-cursor

function ↑ Functions

(: mutablemap-cursor (-> (MutableMap %k %v) (MutableMapCursor %k %v)))

Creates an iteration cursor positioned before the first entry.

m
The map to traverse.
returns
A new cursor positioned before the start.
(def c (mutablemap-cursor m))
(let loop ()
  (cond
    ((mutablemap-cursor-done? c) unit)
    (else
     (def (k v) (mutablemap-cursor-current c))
     (println (str k ": " v))
     (loop))))

Call mutablemap-cursor-done? before each entry, then read the entry with mutablemap-cursor-current. Standard for-each and :for loops handle this automatically.

See also: mutablemap-cursor-done?, mutablemap-cursor-current, mutablemap-for-each

mutablemap-cursor-done?

function ↑ Functions

(: mutablemap-cursor-done? (-> (MutableMapCursor %k %v) bool))

Advances the cursor to the next entry; returns #t if finished.

c
The cursor to advance.
returns
#t if iteration has finished, #f if positioned on an entry.

Advances cursor position. Call once before reading each entry with mutablemap-cursor-current.

See also: mutablemap-cursor-current

mutablemap-cursor-current

function ↑ Functions

(: mutablemap-cursor-current (-> (MutableMapCursor %k %v) (Tuple %k %v)))

Returns the current entry at the cursor as a (Tuple k v).

c
The cursor.
returns
The (Tuple key value) pair at the current position.

Call only when mutablemap-cursor-done? has returned #f.

See also: mutablemap-cursor-done?

mutablemap-for-each

function ↑ Functions

(: mutablemap-for-each (-> (-?-> %k %v void) (MutableMap %k %v) void))
(mutablemap-for-each f m)

Invokes a callback with the key and value of each entry.

f
Callback function taking (key, value) arguments.
m
The map to iterate over.
(mutablemap-for-each (fun (k v) (println (str k ": " v))) counts)

Passes key and value as two separate arguments to f. Modifying m during callback execution raises System.InvalidOperationException.

See also: mutablemap-cursor, for-each

list->mutablemap

function ↑ Functions

(: list->mutablemap (-> (List (Tuple %k %v)) (MutableMap %k %v)))
(list->mutablemap xs)

Constructs a new mutable map from a list of key-value pairs.

xs
List of (Tuple key value) pairs. Duplicate keys keep the last value.
returns
A new mutable map.

See also: mutablemap->list, seq->mutablemap

mutablemap->list

function ↑ Functions

(: mutablemap->list (-> (MutableMap %k %v) (List (Tuple %k %v))))
(mutablemap->list m)

Converts map entries to a list of (Tuple key value) pairs.

m
The source map.
returns
A new list containing all entries in traversal order.

See also: list->mutablemap

vec->mutablemap

function ↑ Functions

(: vec->mutablemap (-> (Vec (Tuple %k %v)) (MutableMap %k %v)))
(vec->mutablemap v)

Constructs a new mutable map from a vector of key-value pairs.

v
Vector of (Tuple key value) pairs. Duplicate keys keep the last value.
returns
A new mutable map.

See also: mutablemap->vec, seq->mutablemap

mutablemap->vec

function ↑ Functions

(: mutablemap->vec (-> (MutableMap %k %v) (Vec (Tuple %k %v))))
(mutablemap->vec m)

Converts map entries to a vector of (Tuple key value) pairs.

m
The source map.
returns
A new vector containing all entries in traversal order.

See also: vec->mutablemap

seq->mutablemap

function ↑ Functions

(: seq->mutablemap (-> (Seq (Tuple %k %v)) (MutableMap %k %v)))

Constructs a new mutable map from a sequence of key-value pairs.

xs
Sequence of (Tuple key value) pairs. Duplicate keys keep the last value.
returns
A new mutable map.

Later entries overwrite earlier entries with matching keys, matching mutablemap-set! semantics.

See also: mutablemap->seq

mutablemap->seq

function ↑ Functions

(: mutablemap->seq (-> (MutableMap %k %v) (Seq (Tuple %k %v))))

Views map entries as a sequence of (Tuple key value) pairs.

m
The source map.
returns
A Seq iterating over entries of m.

Views the live map. Modifying the map during sequence traversal raises System.InvalidOperationException. To take an immutable snapshot, use mutablemap->list or mutablemap->vec.

See also: seq->mutablemap, mutablemap->list

map->mutablemap

function ↑ Functions

(: map->mutablemap (-> (Map %k %v) (MutableMap %k %v)))
(map->mutablemap m)

Constructs a new mutable map from a persistent Map.

m
The source persistent map.
returns
A new mutable map containing all entries.

See also: mutablemap->map

mutablemap->map

function ↑ Functions

(: mutablemap->map (-> (MutableMap %k %v) (Map %k %v)))
(mutablemap->map m)

Converts a mutable map into an immutable persistent Map.

m
The source mutable map.
returns
A new persistent Map. Subsequent changes to m do not affect it.

See also: map->mutablemap

mutablemap->str

function ↑ Functions

(: mutablemap->str (-> (MutableMap %k %v) string))
(mutablemap->str m)

Deprecated: use displayed. Formats the map as text in the form #mmap(k v …).

m
The map to format.
returns
Formatted string representation using displayed for each key and value.
(displayed (list->mutablemap (list (Tuple 1 10))))   ; "#mmap(1 10)"

The same text as displayed gives for a mutable map. Formats entries without parentheses around pairs.