envzn
0.8 · beta · not released

Library / Collections / Sequences / Stack

CLASSEXTENDS Array<T>

Stack

Defines the Stack[T] class per ENVZN_CONSTITUTION §Stack.

Constructors 2

INIT()

default constructor

INIT(int64 presized)

for presized Stack allocation

Methods 9

OVERRIDE METHOD clone() RETURNS Stack[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 push(T value) RETURNS STATUS
modifies

Push value onto the top. Per §10.2 the bare-named form consumes the source — value is moved through Array's owning append onto the stack's backing.

MODIFY METHOD pushCopy(REFERENCE T value) RETURNS STATUS
modifies

Deep-copy form of push. value stays valid for the caller; the clone is what the backing array stores.

MODIFY METHOD pop() RETURNS | T
modifies

Remove and return the top element. Pipe-XOR: SUCCESS populates value; FAILURE when the stack is empty. Depends on Array providing popLast() with move-out semantics for class T.

METHOD peek() RETURNS | REFERENCE T
reads

Return (without removing) the top element as a REFERENCE handle. Multi-return per the kernel peek contract — STATUS == FAILURE when empty, SUCCESS otherwise. Delegates to Array.peekLast.

MODIFY METHOD popLast() RETURNS | T
modifies

Remove and return the last element. FAILURE if empty. Ownership of the returned element transfers to the caller. O(1). For T IS Inoperative (opaque): always returns FAILURE — the stored payload is opaque and can't be lifted out by-value.

MODIFY METHOD popFirst() RETURNS | T
modifies

Remove and return the first element. FAILURE if empty. O(n) — shifts every remaining element down by one. For T IS Inoperative: always returns FAILURE (see popLast).

METHOD peekLast() RETURNS | REFERENCE T
reads

Read the last element without removing it. STATUS is FAILURE when the array is empty (value is EMPTY); SUCCESS otherwise with value referencing the element in place. The REFERENCE handle is valid only while no mutation occurs on the Array.

METHOD peekFirst() RETURNS | REFERENCE T
reads

Read the first element without removing it. Same pipe-XOR shape as peekLast.