plum

module std
import std/Bool
import std/Number

# A fixed-length, O(1)-indexable array of `T`, backed directly by a wasm-gc
# `array<anyref>` — every `Array[T]` specialization (`Array$Int`, `Array$Str`,
# ...) shares the SAME underlying wasm array type (see
# `plum-wasm-codegen::GcTypeRegistry::array_type_idx`), exactly like `[]Byte`
# reuses `Str`'s own array type. `init`/`get`/`set`/`length` are compiler
# intrinsics (see `compileIntrinsicFnBody`) — there's no way to express raw
# array allocation/indexing in Plum source itself.
#
# LIMITATION: `T` must be a reference type (a `type`/`enum` value, `Str`,
# `List`, etc.) — every element is stored as a boxed `anyref` and `get`
# narrows it back to `T` via `ref.cast`. A primitive `T` (`Int`/`Float`/`Bool`/
# `Byte`) is NOT supported (no boxing/unboxing exists yet) and will not
# codegen correctly. Nothing in `libs/std` instantiates `Array` with a
# primitive `T` today — the only user is `Map[K, V]`'s bucket array,
# `Array[List[Pair[K, V]]]`.
#
# `init()` is deliberately zero-arg (no `Array[T](n)` constructor exists) —
# `class_call`'s grammar (`Type[Generics](...)`) only ever accepts `name:
# value` field arguments or an empty arg list, never bare positional ones
# (see `tooling/tree-sitter-plum/grammar.js`'s `class_argument_list`), and
# `Array` has no real fields for a keyword arg to bind to. Building a
# specific-length array is `push`ing onto an empty one `n` times instead
# (`Map`'s bucket array does exactly this at construction) — `push` itself
# has no in-place "grow" to fall back on either (a wasm-gc `array` is a
# fixed-length allocation once made), so it allocates a new, one-longer array
# and copies, same amortized-growth idea as `Buffer`'s own `write`.
#
# New elements start out `None`-shaped — really a null `anyref` under the
# hood — so `get` on an index that was never `set` traps rather than
# returning some default `T` value (there is no way to conjure a default `T`
# generically).
enum Array[T] =
  | Array

  # A new, empty array.
  fun init() -> Array[T] =
    todo

  # The element at index `i`. Traps if `i` is out of range or was never `set`.
  fun get(self, i: Int) -> T =
    todo

  # Overwrites the element at index `i` with `v`. Traps if `i` is out of range.
  fun set(self, i: Int, v: T) -> Unit =
    todo

  # Number of slots in the array.
  fun length(self) -> Int =
    todo

  # Returns a NEW array, one longer than `self`, with `v` appended at the end
  # — `self` itself is left untouched (this allocates and copies, it does not
  # mutate in place). Callers grow in a loop by reassigning: `arr =
  # arr.push(v)`.
  fun push(self, v: T) -> Array[T] =
    todo