Module collections 

Collection operations: indexing, length, membership, mutation, set algebra.

Structs

ReferenceScope

RAII guard: run the closure / dynamic extent under reference semantics on this thread. Re-entrant (nested PE calls compose). See [FORCE_REFERENCE].

Functions

assert_hashable_key

A Map key must be TRANSITIVELY immutable: a List/Set/Map key (even one buried inside a tuple or struct) is a shared handle whose later mutation would silently corrupt the map, so the insert refuses it outright with a catchable error. Tuples and structs of immutable parts are VALUE keys.

contains

Membership: values_equal scan for Set/List, key lookup for Map, substring/char for Text.

index_get

1-based index for List/Tuple/Text; key lookup for Map; Text-keyed field read for Struct.

index_set

Set item idx of collection to value — 1-based list set, or map insert. (Struct field set needs an environment reassign and stays engine-side.)

intersection

Set intersection — left’s elements present in right, in left’s order.

iteration_snapshot

The Repeat iteration snapshot: the collection is materialized ONCE before the loop, so mutation inside the body cannot extend or shrink the iteration. Text iterates per char (as 1-char Texts); a Map yields (key, value) Tuples in its (nondeterministic) iteration order.

length_of

length of x. NOTE: Text length is BYTES (while Text indexing is chars) — a pinned tree-walker behavior.

list_pop

Pop from list — removes and returns the last element, or Nothing when the list is empty (popping an empty list is NOT an error).

list_push

Push value to list — mutates the shared allocation in place.

push_to_struct_field

Push value to obj's field — pushes into a struct’s List field through the shared allocation. Every error string is the spec.

range

a to b — inclusive integer range as a List.

reference_scope_active

Whether the current thread is inside a ReferenceScope. Consulted by the AOT runner so a child process compiled from PE source inherits reference semantics (LOGOS_VALUE_SEMANTICS=0).

remove_from

Remove value from set/map.

set_add

Add value to set — dedups via values_equal.

slice

1-indexed, inclusive-end slice of a List. Out-of-range slices are empty.

text_is_ascii

Whether a Text is pure ASCII, answered in O(1) per call via the same (is_ascii, char_len) cache the indexing hot path uses (the first call for a given Rc/length pays the vectorized is_ascii() scan, every later one is a cache hit). The VM’s tier-up seam asks this on every hot back-edge crossing and again at every region entry: a Text-as-bytes pin is sound ONLY for ASCII (char index == byte index, char count == byte length), so a non-ASCII Text must never pin.

union

Set union — left’s elements, then right’s not already present.

value_semantics_enabled

Whether Mutable Value Semantics (copy-on-write for collections) is enabled. Value semantics is the DEFAULT (all four tiers — tree-walker, VM, AOT, JIT — implement it). LOGOS_VALUE_SEMANTICS=0 restores the historical reference semantics (escape hatch). A thread-local ReferenceScope also forces reference semantics for the duration of compile-time PE / self-interpreter execution (bootstrap-scope). The env var is read once and cached; the thread-local check is a single Cell read, so the hot path stays cheap.

with_reference_semantics

Run f with reference semantics forced on this thread (the bootstrap scope).