lib/map.x

Hash table mapping Var keys to Var values.

Primary API

Map

Map.cleanup

meta native void Map.cleanup(Map value)

Releases this Map and both backing Blocks without freeing stored values.

Source: lib/map.x:236

Map.contains

int Map.contains(Map map, Var key)

Returns one when key is present, or zero for a null map.

Source: lib/map.x:87

Map.copy

Map Map.copy(Map map)

Returns a fresh shallow copy in the current Scope. The result has independent table storage but copies native key and value fields. A null input produces a fresh empty map.

Raises: an allocation, size, or invariant cause while copying.

Source: lib/map.x:87

Map.enumerate

Iter Map.enumerate(Map map, Iter dest)

Initializes dest to yield canonical (key value) Lists in bucket order. The caller owns dest, and the iterator borrows map; both must remain live during traversal. A null dest returns NULL, and a null map is exhausted. Each step boxes both fields and interns two List cells. Each cell belongs to the pool owning its canonical match, which may be an ancestor pool, or to the current pool when newly allocated. Structural mutation invalidates the iterator. Each MapLongDouble pull allocates its long key as a Var in the current Scope; the yielded List and anything retaining it must not outlive that Scope.

Raises: <alloc-fail> or <size-limit> while interning the List, and for MapLongDouble, <alloc-fail> or <bad-enc> while boxing its key. Shared causes do not return from the pull.

Source: lib/map.x:231

Map.get_hashed

meta native Var Map.get_hashed(Map map, Var key, unsigned key_hash)

Returns the value stored under key, or void when absent, probing with the caller’s precomputed key_hash. key_hash must be Var.hash of key; another value reports the key as absent. This serves a caller that probes several Maps with one key, and is Map.get in every other respect. A null Map reports absence.

Raises: a cause raised by custom key equality. Hashing happens in the caller, so a void key raises there instead.

Source: lib/map.x:148

Map.getdefault

Var Map.getdefault(Map map, Var key, Var defval)

Returns the value for key, or defval without inserting it. A null map is treated as an empty one.

Source: lib/map.x:87

Map.iter

Iter Map.iter(Map map, Iter dest)

Initializes dest as a single-pass iterator over boxed values. The caller owns dest, and the iterator borrows map; both must remain live during traversal. A null dest returns NULL. Values follow bucket order, a null map is exhausted, and structural mutation invalidates the iterator.

Source: lib/map.x:231

Map.keys

Iter Map.keys(Map map, Iter dest)

Initializes dest as a single-pass iterator over boxed keys. The caller owns dest, and the iterator borrows map; both must remain live during traversal. A null dest returns NULL. Keys follow bucket order, a null map is exhausted, and structural mutation invalidates the iterator. MapIntInt and both String-keyed families box keys without allocation. Each MapLongDouble pull allocates its long key as a Var in the current Scope; the yielded Var and anything retaining it must not outlive that Scope.

Raises: MapLongDouble iteration may raise <alloc-fail> or <bad-enc> while boxing a key.

Source: lib/map.x:231

Map.len

unsigned Map.len(Map map)

Returns the number of entries, or zero for a null map.

Source: lib/map.x:87

Map.merge

Map Map.merge(Map map, Map other)

Copies every entry of other into map and returns the destination. other wins conflicts. A null other is a no-op; a null destination is replaced by a fresh map. When a supplied destination fails partway, entries already copied remain; a newly created destination is discarded.

Raises: an allocation, size, or invariant cause while inserting.

Source: lib/map.x:87

Map.new

Map Map.new(void)

Returns a fresh empty map owned by the current Scope. The initial table has two buckets and grows automatically.

Raises: <alloc-fail> or <size-limit> when storage cannot be created.

Source: lib/map.x:87

Map.postfixindex

Var Map.postfixindex(Map map, Var key, Symbol op)

Applies postfix ++ or -- and returns the previous value. The key must already exist. A failing value operation leaves the entry unchanged.

Raises: <bad-arg> for a null map or absent key, <void-op> for a void key, or a cause from Var.postfix for an unsupported value or operation.

Source: lib/map.x:128

Map.set

void Map.set(Map map, Var key, Var val)

Copies key and val into the table, replacing an existing value. Insertion invalidates live cursors and iterators; replacement does not.

Raises: <bad-arg> for a null map, or an allocation, size, or invariant cause while inserting. Allocation and size failures leave the table unchanged.

Source: lib/map.x:87

Map.setdefault

Var Map.setdefault(Map map, Var key, Var defval)

Returns the value for key, inserting defval when absent. Insertion copies the native key and value fields and invalidates live cursors and iterators; an existing-key read does not mutate the table.

Raises: <bad-arg> for a null map, or an allocation, size, or invariant cause while inserting. Allocation and size failures leave the table unchanged.

Source: lib/map.x:87

Map.setindex

Var Map.setindex(Map map, Var key, Var val)

Stores val under key and returns val. This is the bracket-facing form of Map.set, with the same cursor invalidation and failure behavior.

Source: lib/map.x:87

Map.truth

int Map.truth(Map map)

Returns one when map contains an entry.

Source: lib/map.x:87

Map.try_del

int Map.try_del(Map map, Var key, Var &?out)

Removes key, writes its value to out, and returns one when present. A null map, null out, or absent key returns zero without writing or mutation. Successful removal invalidates live cursors and iterators.

Source: lib/map.x:87

Map.try_get

int Map.try_get(Map map, Var key, Var &?out)

Writes the value for key to out and returns one when present. A null map, null out, or absent key returns zero without writing.

Source: lib/map.x:87

Map.try_next

int Map.try_next(Map map, unsigned &?cursor, Var &?key, Var &?val)

Writes the next bucket’s key and value, advances cursor, and returns one. Initialize the caller-owned cursor to zero. A null argument or exhaustion returns zero without changing key or val. Traversal follows bucket order, not insertion order, and structural mutation invalidates the cursor.

Source: lib/map.x:87

Map.updateindex

Var Map.updateindex(Map map, Var key, Symbol op, Var rhs)

Applies op to the value for key and returns the stored result. + inserts a numeric rhs when the key is absent; other updates require an existing key. A failing value operation leaves the entry unchanged.

Raises: <bad-arg> for a null map or missing required key, <void-op> for a void key or value, a cause from Var.update, or an allocation, size, or invariant cause while inserting.

Source: lib/map.x:105

Map.write_str

Buffer Map.write_str(Map map, Buffer out)

Appends the typed-Map display text in bucket order.

Source: lib/map.x:230

Advanced and interop API

Map

Map.compare

int Map.compare(Map a, Map b)

Compares typed Maps by size and then sorted native key/value contents. Identical handles compare equal and NULL sorts first. Neither Map is mutated. Raises: <alloc-fail> while creating temporary storage, or any cause from key or value comparison.

Source: lib/map.x:230

Map.equal

int Map.equal(Map a, Map b)

Reports key/value equality independent of bucket and insertion order. Two null maps compare equal; a null and a nonnull map compare unequal.

Source: lib/map.x:87

Map.repr

String Map.repr(Map map)

Returns the readable typed-Map representation.

Source: lib/map.x:230

Map.str

String Map.str(Map map)

Returns the typed-Map display String.

Source: lib/map.x:230

Map.update_n

Self Map.update_n(Self map, unsigned pair_count, ...)

Adds exactly pair_count key/value pairs to map in argument order. Arguments alternate Var keys and values. A null Map returns NULL without reading them. Each completed pair remains if a later pair fails. Inserting a new key invalidates active traversal; replacing an existing value does not.

Raises: the same causes as Map.set.

Source: lib/map.x:161

Map.write_repr

Buffer Map.write_repr(Map map, Buffer out)

Appends the readable typed-Map representation in bucket order.

Source: lib/map.x:230

Convenience API

Map

Map.del

Var Map.del(Map map, Var key)

Removes key and returns its value. Successful removal invalidates live cursors and iterators. Prefer try_del when absence is an ordinary outcome. Boxed families return void for absence; native families raise <bad-arg>.

Source: lib/map.x:87

Map.get

Var Map.get(Map map, Var key)

Returns the value for key. Prefer try_get when absence is an ordinary outcome. Boxed families return void for absence; native families raise <bad-arg>.

Source: lib/map.x:87

Map.getindex

Var Map.getindex(Map map, Var key)

Returns the value selected by bracket indexing. This is the bracket-facing form of Map.get, with the same failure behavior. Prefer bracket indexing in ordinary code.

Source: lib/map.x:87

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Map

Map.export_to

void Map.export_to( Map map, Context source, VarExportContextFn export_value, Scope *scope)

Exports every key and value, rebuilds the table, then moves its Blocks. The borrowed export_value callback runs synchronously for each stored key and value and may return replacement Vars. Rebuilding is required because an exported key may hash differently. On success the old backing Blocks are freed, the rebuilt Blocks move into scope, and the Map identity remains unchanged. Context moves that identity before this call to break cycles.

A failure while staging leaves the Map’s original records, backing storage, and recorded Scope unchanged. Effects of callbacks that already completed, including nested exports, are not rolled back. Any failure while moving the rebuilt Blocks occurs after the table has replaced the original. A null Map, callback, or Scope pointer does nothing. Raises: <alloc-fail>, <size-limit>, or <invariant> while rebuilding, or any cause from export, key hashing, or moving the rebuilt Blocks.

Source: lib/map.x:189

Map.new_capacity

Map Map.new_capacity(unsigned capacity)

Returns a fresh empty map with exactly capacity buckets. The result and its backing arrays belong to the current Scope. capacity must be a power of two of at least two.

Raises: <bad-arg> for another capacity, or <alloc-fail> / <size-limit> when storage cannot be created.

Source: lib/map.x:87

Public types

Map

typedef struct Map { Scope scope, Bytes hashes, entries; unsigned used; unsigned capacity; unsigned mask; } *Map

Scope-backed mutable hash table from Var keys to Var values. The Map records the Scope used for its two backing Blocks. Context moves the Map allocation itself before recursively exporting those Blocks. Stored Var bits are shallow and retain no pointee; those values must remain valid while the Map can read, compare, hash, or return them. A valid empty Map is allocated and distinct from NULL.

Source: lib/map.x:30

Design notes

Map uses Robin Hood hashing split across two scope-owned Blocks. The hash Block holds one 32-bit hash per bucket, zero for an empty bucket; the entry Block holds the Var key and value at the same bucket index. Lookups probe the compact hash Block and touch an entry only when its hash matches. Capacity is always a power of two and probe distances are computed as needed.

Deletion back-shifts hashes and entries together to close holes. Structural mutation invalidates traversal state. Keys and values are stored as Var bits; the Map does not free pointer-bearing payloads or canonical values reachable through them.

Tests and examples

make verify (unittest/test-map.x) and make examples (docs-word-count).