Library / Collections / Sequences / Array
Array
Opaque-size, ordered, indexable collection.
Constructors 2
INIT()Default constructor
INIT(int64 presized)
Presized constructor to reduce the malloc activity
Methods 20
METHOD iterator() RETURNS ArrayIterator[T]reads
Returns a fresh ArrayIterator[T] at position 0 — the FINAL
concrete iterator class (covariant against the inherited
Iterable.iterator() shape). Each call returns an independent
iterator; multiple may exist concurrently on the same Array.
The concrete return type lets the emitter inline hasNext() /
next() on FOR/IN loops over Array; callers binding to
BidirectionalIterator OF T still typecheck via class-to-
interface upcast.
METHOD size() RETURNS int64reads
Number of elements currently stored. Read-only, O(1).
METHOD isEmpty() RETURNS booleanreads
Countable — the other half of size(). Array carries the whole
Collection contract now (size, isEmpty, iterator), and none of
the three asks anything of T: that is what lets Array join Collection
while keeping its qualifier at Cloneable-or-primitive.
METHOD clone() RETURNS Array[T]reads
Deep copy. Each element is cloned via T->clone(); T must
implement Cloneable when T is a class type.
For T IS Inoperative (opaque only today): returns
an empty Array — Inoperative values are opaque so we can't
preserve them on clone.
MODIFY METHOD append(T value) RETURNS STATUSmodifies
Append value to the end. Per §10.2 the bare-named form
consumes the source — value is moved into the array and
the caller's source is poisoned (post-call use is a compile
error). For a deep-copy variant that leaves the caller's source
valid, use appendCopy. O(1) amortised.
EMPTY-reject (class-typed T only): an EMPTY class-handle
value is refused with FAILURE before any state change — the
collection only ever holds real owned objects, so every
subsequent peek/pop/at sees a populated slot. Per §9.3 IS VALID
is meaningful only on class handles; the check is gated via
WHEN T IMPLEMENTS Cloneable (the kernel's proxy for
"class-shaped T") and elided for primitive / struct T.
MODIFY METHOD appendCopy(REFERENCE T value) RETURNS STATUSmodifies
Append a deep copy of value to the end. value stays fully
valid for the caller after the call. For class-typed T, the
copy goes through T->clone(); T must implement Cloneable. For
primitive/struct T, value-copy. O(1) amortised. Returns SUCCESS,
or FAILURE if backing storage rejected the insert.
METHOD __op_index__(int64 index) RETURNS MUTABLE REFERENCE Treads
Reference to element at index i. Throws IndexOutOfBoundsError if i is out
of range — bounds check lives in _EvArray<char32_t>::operator[]. A
borrow-propagating ("mirror") accessor: the result mirrors the receiver's
mutability (mutable array -> MUTABLE REFERENCE, const -> read-only REFERENCE).
METHOD subscript(int64 index) RETURNS | MUTABLE REFERENCE Treads
Bounds-checked reference into the element at index — the lowering
target for arr[idx] syntax on Array[T] receivers, and a borrow-
propagating ("mirror") accessor: SUCCESS populates result with a
reference that mirrors the receiver's mutability (a mutable array
yields a MUTABLE REFERENCE for in-place modification, a const array a
read-only REFERENCE); out-of-bounds populates s with FAILURE. Caller
pattern: IF arr[i] THEN { binding REFERENCE T r =@ $RETURNED, then using r,
} ELSE { log($!) }. The
reference is valid only while the Array is not mutated (mutation lock).
Replaces the former at / subscript / mutableAt accessor set.
MODIFY METHOD setAt(int64 index, T value) RETURNS STATUSmodifies
Replace the element at index. Per §10.2 the bare-named form
consumes the source — value is moved into the array and
the caller's source is poisoned. The previous element is
destroyed. Returns FAILURE on out-of-bounds.
MODIFY METHOD setAtCopy(int64 index, REFERENCE T value) RETURNS STATUSmodifies
Replace the element at index with a deep copy of value.
value stays valid for the caller. Throws IndexOutOfBoundsError
on bad index.
MODIFY METHOD insertAt(int64 index, T value) RETURNS STATUSmodifies
Insert value at index, shifting subsequent elements right
by one. Per §10.2 the bare-named form consumes the source —
value is moved into the array and the caller's source is
poisoned. Valid index is 0..length inclusive (index == length
appends). Returns FAILURE on out-of-bounds. O(n) — shifts
everything to the right of the insertion point.
MODIFY METHOD insertAtCopy(int64 index, REFERENCE T value) RETURNS STATUSmodifies
Insert a deep copy of value at index. value stays valid.
Same index rules and complexity as insertAt.
MODIFY METHOD swap(int64 i, int64 j) RETURNS STATUSmodifies
Exchange the elements at i and j in place. Nothing is copied and no
slot is ever empty — this is how an element moves WITHIN an array, since
arr[k] := arr[j] is E6040 (a subscript is a reference to a slot the
array keeps owning). Returns FAILURE if either index is out of bounds.
MODIFY METHOD replace(int64 index, T value) RETURNS | Tmodifies
Put value at index and hand back the element it displaced. Per
§10.2 value is consumed. Unlike setAt, which destroys the previous
element, this returns it — the owned counterpart of reading arr[i].
Pipe-XOR: FAILURE on out-of-bounds. O(1): the new element is parked at
the tail, swapped into place, and the old one is removed from the tail,
where removal shifts nothing.
MODIFY METHOD remove(int64 index) RETURNS | Tmodifies
Remove the element at index and return it. Pipe-XOR:
SUCCESS populates removed with the value moved out of the
array; FAILURE populates status with the bounds violation.
Subsequent elements shift down. O(n). index is int64.
MODIFY METHOD clear() RETURNS voidmodifies
Remove all elements; the array becomes empty.
METHOD map(LAMBDA func) RETURNS Array[T]reads
Apply func to every element; return a new Array with the
transformed values, in the same order.
METHOD filter(LAMBDA pred) RETURNS Array[T]reads
Return a new Array containing only the elements for which
pred(elem) is TRUE, in their original order.
MODIFY METHOD reduce(REFERENCE T initial, LAMBDA acc) RETURNS Tmodifies
Fold left: starting with initial, repeatedly apply
acc(accumulator, elem) for each element in order. Returns
the final accumulator value.
MODIFY METHOD shuffle(MUTABLE REFERENCE Shuffler rng) RETURNS voidmodifies
Shuffleable OF T — in-place Fisher-Yates.
Lives on Array, not OrderedArray, so every subclass inherits it. It
costs Array nothing: the storage's swap works for every T Array's
qualifier admits, so no interface requirement is added by its being here. It
was also the one method whose presence on OrderedArray contradicted
that class: shuffling destroys exactly the ordering the name promises. Walks from the last index
down, swapping each element with a uniformly-chosen earlier-or-equal
slot drawn from rng. The exchange is the storage's own swap: no
clones, one form for every T. (It used to clone both elements of a
class T and move the clones back in — two deep copies per step.)