Core collections

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. push, get, set and remove take the fallible path, so they need ! or catch. length stays infallible.


    values ~= {1, 2, 3}

    ~values.push(4) catch:
    ;

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

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

    count = values.length()

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 import @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 five 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 | push(value) | 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. Fallible operations return through the builtin Error! channel.

Source-visible surface

Authors interact with collections through language-level syntax and receiver methods, not through direct imports of @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 or fails with Error!
remove(index) removes and returns the element at index or fails with Error!
length() returns the logical length as Int

get, set, push and remove take the fallible path. length stays infallible. set, push and remove require mutable receiver access through ~.


    values ~= {1, 2, 3}

    ~values.push(4) catch:
    ;

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

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

    count = values.length()

No direct import

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

Unsupported source forms

Direct imports of @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. 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, fixed-capacity collections and specialised collection variants. See progress matrix for current status.

Related concepts

For collection literal syntax and typing see Collections.
For the full collection method contract see Collection operations.
For package origin and backing see Package origins and backing.