Documentation / Core packages / Core collections

Core collections

Moth collections store ordered values through language-owned literals and methods backed by @core/collections. The package remains implicit because collection syntax belongs to the language rather than a user dependency clause.

Collection methods

Collections hold ordered groups of values. You create them with literals and work with them through built-in methods.

Creating collections

Growable collections use {T}. Fixed collections use {N T} with a compile-time maximum length.

values ~= {1, 2, 3}
empty_values ~{Int} = {}
fixed_values ~{2 Int} = {}

Non-empty literals infer their element type from their items. Empty literals need an explicit collection type.

Common methods

Collection methods use receiver syntax. get, set and remove take the fallible path, so they need ! or catch. length stays infallible.

push depends on the collection. A growable {T} grows to make room, so its push is infallible. A fixed {N T} can be full, so its push is fallible.

values ~= {1, 2, 3}

~values.push(4)

first = values.get(0) catch:
    then 0
;

~values.set(1, 99) catch:
;

count = values.length()
fixed_values ~{2 Int} = {1}

~fixed_values.push(2) catch:
;

push appends after the last element. get reads at an index. set replaces an element. remove takes an element out and shifts later elements down. length returns the logical length, not the fixed capacity. For the full language rules around collection literals, mutability and fixed capacity, see Collections. For the binding-backed contract behind these methods, see Core collections advanced.

@core/collections forms the binding-backed Core package that provides runtime functions for compiler-owned collection methods. Authors do not bind @core/collections directly. The compiler lowers collection receiver methods to calls against this package.

@core/collections belongs to the Core origin package family with ExternalBinding backing. See Package origins and backing for origin and backing rules.

Binding-backed behaviour

The package registers six host functions that implement the compiler-owned collection member operations:

Host function

Compiler-owned member

Receiver access

__moth_collection_get

get(index)

shared

__moth_collection_set

set(index, value)

mutable

__moth_collection_push_growable

push(value) on a growable {T}

mutable

__moth_collection_push_fixed

push(value) on a fixed {N T}

mutable

__moth_collection_remove

remove(index)

mutable

__moth_collection_length

length()

shared

These host functions use inferred ABI types for the collection element and value parameters. The index parameter is I32. The length return is I32. Both push helpers return no success value. Source-visible failure still travels through the builtin Error! channel: fixed push fails this way only when the collection is full, while growable push has no failure path and allocation exhaustion traps rather than entering Error!.

The single source spelling push(value) resolves once during typed AST construction: the receiver's collection shape selects the growable or fixed host function, and HIR and the backends consume the resolved operations without re-inspecting the receiver type.

Source-visible surface

Authors interact with collections through language-level syntax and receiver methods, not through direct dependencies on @core/collections. The compiler-owned methods include:

  • get(index) returns the element at index or fails with Error!
  • set(index, value) replaces the element at index or fails with Error!
  • push(value) appends value after the last element. One spelling serves both shapes: on a growable {T} it is infallible and returns no value; on a fixed {N T} it returns no success value and fails with Error! only when the collection is full
  • remove(index) removes and returns the element at index or fails with Error!
  • length() returns the logical length as Int

get, set, remove and fixed-collection push take the fallible path. length and growable push stay infallible. set, both push forms and remove require mutable receiver access through ~. Both push forms return no success value, and growable push rejects catch and postfix !.

values ~= {1, 2, 3}

~values.push(4)

first = values.get(0) catch:
    then 0
;

~values.set(1, 99) catch:
;

count = values.length()

No direct dependency

@core/collections carries no source-visible dependency surface. Do not write a dependency clause for it. The package exists to back the compiler-owned methods that receiver syntax invokes.

Unsupported source forms

  • Direct dependencies on @core/collections are not part of the author surface.
  • Square-bracket indexing is not supported. Use get and set.
  • Assignment through get was removed.
  • Builtin member arguments are positional-only. Named arguments are not supported.

Backend behaviour

HTML-JS lowers the host functions to JavaScript runtime helpers, including separate growable and fixed push helpers. HTML-Wasm lacks a Wasm lowering for these functions. See progress matrix for current target availability.

Deferred surfaces

Deferred collection surfaces include HTML-Wasm lowering, map operations as direct host functions, collection equality, collection iteration protocol, sortable collections, deque operations and specialised collection variants. See progress matrix for current status.

Related concepts