plum

# Design: wire up List's remaining methods

## Problem

`libs/std/list.plum`'s `List` (a generic, mutable doubly-linked list backed by

`Node(a)` with `head`/`tail`/`size` fields) has `get`, `length`, `each`, `map`,

`first`, and `last` already implemented and working. `add`, `set`, `removeAt`,

`remove`, `clear`, and `reverse` are still `todo` stubs. This was blocked on

two prerequisites that are now both done: field/attribute assignment

(`self.head = ...`, needed to mutate the linked structure) and variadic

parameters (`values: ...a`, needed by `add`'s signature). `join` is not one of

the six originally-scoped methods, but it separately calls `Buffer()` (an

undeclared type) and `v.toStr()` on a generic-typed value (which would need

trait-bounded dispatch — `plum-checker` doesn't process trait declarations at

all) — both unrelated to this cycle's actual blockers, so it's included here

with a simpler fix instead of being deferred again.

## Scope

In scope: `add`, `set`, `removeAt`, `remove`, `clear`, `reverse`, `join`.

Out of scope (untouched, still `todo`, not part of README's original gap and

not addressed here): `sort`, `find`, `contains`, `flatMap`, `retain`, `reject`,

`any`, `every`, `reduce`, `sublist`, `take`, `skip`, `drop`, `sample`,

`shuffle`, `partition`, `chunk`, `groupBy`. `Map`'s own methods (a separate

class in `libs/std/map.plum`) are untouched.

Two corrections to the existing (buggy/inconsistent) doc comments and one

signature change, confirmed with the project owner:

- `add`'s doc comment currently says "to the start" but `init<List>` calls

  `List().add(values)` expecting insertion order to be preserved, which only

  works if `add` appends to the *tail*. The comment is stale; `add` appends.

- `reverse`'s current signature, `reverse<List>(self, v: fn(a) -> Bool) ->

  List`, has a predicate parameter that doesn't match its own doc comment

  ("returns a new list with the elements in reverse order") — a copy-paste

  artifact from a filter-style method. Signature becomes `reverse<List>(self)

  -> List`, no predicate.

- The mutable, doubly-linked `Node`/`head`/`tail`/`size` design is kept as-is

  (not rewritten as an immutable `Cons`/`Empty` enum) — it's already

  half-built and tested (`get`/`length`/`each`/`map`/`first`/`last` all depend

  on it), and it gives O(1) append/length, which a cons-list can't for `add`'s

  agreed append-in-order semantics.

## Method designs

All methods below operate on the existing `type Node(a) = value: a, prev:

Option[Node], next: Option[Node]` and `type List(Stringable)(a: Stringable) =

head: Option[Node], tail: Option[Node], size: Int` — no type changes.

**`add<List>(self, values: ...a)`**: for each value (in call order, via `for v

in values`), construct `newNode = Node(value: v, prev: self.tail, next: None)`,

link it after the current tail (`self.tail`'s node gets `.next = Some(newNode)`

if a tail exists, otherwise this is the first node so `self.head =

Some(newNode)` too), then `self.tail = Some(newNode)` and `self.size = self.size

+ 1`.

**`set<List>(self, i: Int, v: a) -> Option(a)`**: traverse from `self.head`

exactly like `get` does; at the matching index, capture the node's current

`value`, assign `node.value = v`, and return `Some(oldValue)`; if the traversal

runs off the end without finding index `i`, return `None`.

**`removeAt<List>(self, i: Int)`** / **`remove<List>(self, v: a)`**: both

locate a target node (`removeAt` by traversing to index `i`; `remove` by

traversing and comparing `node.value == v`) and, if found, unlink it: its

`prev` node's `next` becomes the target's `next` (or, if the target had no

`prev`, `self.head` becomes the target's `next` — the target was the head);

symmetrically for `next`/`self.tail`. Both decrement `self.size`. Neither

returns a value (matching their current `todo` signatures, which declare no

`-> T`). If the target isn't found, both are a no-op (no error) — this

matches `get`'s existing behavior of returning `None` rather than erroring on

an out-of-range index, so `removeAt`/`remove` follow the same "graceful

no-match" convention already established in this file.

**`clear<List>(self)`**: `self.head = None`, `self.tail = None`, `self.size =

0`.

**`reverse<List>(self) -> List`**: `nl = List()`, then walk `self` from

`self.tail` backward via each node's `.prev` (this naturally visits values in

reverse order), calling `nl.add(value)` for each — reuses `add` rather than

reimplementing low-level linking for the new list.

**`join<List>(self, sep: Str = ",") -> Str`**: rewritten to avoid `Buffer`,

`.toStr()`, and any trait dispatch — builds the result via string

interpolation, which already compiles for `Str`/`Int`/`Bool` element types

(interpolating a `Float` element remains a separate, pre-existing, unrelated

gap — same as everywhere else in the language):

```

join<List>(self, sep: Str = ",") -> Str =

  result = ""

  current = self.head

  while current != None

    match current

      Some(node) =>

        result = "{result}{node.value}{sep}"

        current = node.next

      None =>

        break

  result

```

(This preserves the original `Buffer`-based version's existing quirk of

always appending a trailing separator after the last element — not a

regression, matching prior behavior.)

## Additional fix: `List()` must always give explicit fields

`plum-checker`'s `ClassCall` type-checking only validates whatever fields ARE

given, not that all of a class's fields are supplied — so `List()` (zero

fields) type-checks today. Codegen never initializes an unmentioned field, so

it's left as whatever the WASM linear memory already held there — which, for

memory a bump allocator has never written to before, is zero (WASM memory

starts zero-filled). For `size: Int` that's correctly `0`, but `head`/`tail:

Option[Node]` are enum-tagged, and `Option`'s declaration order (`Some` listed

before `None`) means `None`'s tag is very likely not `0` — so a zero-filled

`head`/`tail` probably decodes as a garbage `Some(...)`, not `None`. This is a

latent bug in the *existing* `init<List>`/`map<List>` methods (both call bare

`List()`), not something newly introduced. Fix: every fresh-empty-list

construction in this cycle — including `init`/`map`'s pre-existing bare

`List()` calls — becomes explicit: `List(head: None, tail: None, size: 0)`.

## Risk: generic class construction inside a generic method of another generic class

`add`'s `Node(value: v, prev: ..., next: ...)` construction is a class

literal for one generic class (`Node(a)`) built inside a method of a

*different* generic class (`List`'s `add<List>`), with `List`'s own type

parameter `a` needing to flow into `Node`'s specialization. Existing

generic-codegen tests cover a generic class's method reading its own field,

and a generic *function* call chain — neither is this exact shape. It should

work given the current monomorphization machinery (both classes are already

generic and specialized elsewhere independently), but it's genuinely

untested. `add` is deliberately the first implementation task so if this

reveals a real compiler gap, it surfaces immediately rather than after

building `set`/`removeAt`/`remove`/`reverse` on top of an unverified

assumption.

## Testing

Each method gets `plum-checker` (where relevant — e.g. `set`'s `Option(a)`

return) and `plum-wasm-codegen` tests exercising it via `run_main`, using

small `Node`/`List`/`Option` fixtures inline in the test source (matching this

project's established testing convention — see e.g.

`generic_method_on_generic_class_runs_correctly` in `codegen_tests.rs`) rather

than depending on cross-file loading of the real `libs/std` files (a separate

concern from this spec). Specifically:

- `add`: append 3 values, confirm `length()` is 3 and traversal order matches

  insertion order (via `get(0)`/`get(1)`/`get(2)`).

- `set`: set an in-range index, confirm the returned `Option` holds the old

  value and `get` reflects the new one; set an out-of-range index, confirm

  `None`.

- `removeAt`/`remove`: remove the head, the tail, and a middle element in

  separate cases; confirm `length()` decrements and neighboring links are

  correct (traverse the remaining list end-to-end).

- `clear`: add elements, clear, confirm `length()` is 0 and `get(0)` is

  `None`.

- `reverse`: build a list, reverse it, confirm element order via `get`.

- `join`: build a list of `Int`s, confirm the joined `Str` matches the

  expected (including the trailing-separator quirk).

## README

Once this lands, remove the `List`-methods-still-`todo` clause from README's

"Known gaps" bullet entirely (all six originally-listed methods, plus `join`,

are done) — the much longer tail of still-`todo` extras (`sort`, `find`,

`flatMap`, etc.) was never part of that bullet's scope and stays unmentioned,

consistent with how the bullet was already scoped before this cycle.