envzn
0.8 · beta · not released

Library / Collections / Sequences / Array

CLASSIMPLEMENTS Cloneable, Collection<T>, Shuffleable<T>

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 int64
reads

Number of elements currently stored. Read-only, O(1).

METHOD isEmpty() RETURNS boolean
reads

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 STATUS
modifies

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 STATUS
modifies

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 T
reads

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 T
reads

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 STATUS
modifies

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 STATUS
modifies

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 STATUS
modifies

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 STATUS
modifies

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 STATUS
modifies

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 | T
modifies

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 | T
modifies

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 void
modifies

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 T
modifies

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 void
modifies

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.)