Core interfaces
The contracts every other family is built on: copying, equality, ordering, hashing, iteration, views, and reading and writing text.
Generated by
bin/build_library_doc.pyfrom the kernel sources. Do not edit by hand: change the generator, or the doc comments inkernel/src/, and re-run it.
Collections and iteration
INTERFACE BidirectionalIterator
BidirectionalIterator OF T — extends ReferenceIterator OF T with reverse traversal. Used by Array, LinkedList, SortedList, Deque per spec L763-768.
- hasPrevious() — TRUE if cursor has not reached the start
- previous() — moves cursor backward, returns the element; STATUS = FAILURE at start
- skipBack(n) — moves cursor backward by n positions; returns the element at the new position, or STATUS = FAILURE if start is reached. Symmetric to skip(n). skipBack(0) is equivalent to peek().
kernel/src/interfaces.ev:458
Methods
METHOD hasPrevious() RETURNS boolean
MODIFY METHOD previous() RETURNS | REFERENCE T
MODIFY METHOD skipBack(uint64 n) RETURNS | REFERENCE T
GROUP Collectable
kernel/src/interfaces.ev:175
INTERFACE Collection
The minimum definition of a Collection container — what every container in the standard library can answer, so that membership of this interface is what marks a type AS a collection.
3 METHODS: iterator() declared here size() and isEmpty() inherited from Countable
contains() is deliberately NOT here, and the reason is the whole shape of
the interface. Containment needs EQUALITY on T, and Array[T] requires only
Cloneable of its elements — so putting contains in the minimum would force
Equatable onto every element type in the language the moment Array joined.
That is the split the industry already divides on: where equality is
UNIVERSAL (Java's Object.equals, Python's eq) a Collection can require
contains, and where equality is OPT-IN (Rust, Swift, C++) it cannot —
Swift's Collection requires iteration and offers contains only as an
extension where Element: Equatable. Envzn is the second kind. Containment
belongs with Searchable OF T, whose find needs exactly the same equality
and of which contains is the boolean shadow.
ITERATION is also the more primitive notion: contains is DERIVABLE from
iterating and comparing, while iteration cannot be derived from containment.
A minimum should be the irreducible core.
The qualifier is deliberately the WIDEST of any container's: iterator(),
size() and isEmpty() ask NOTHING of T, so nothing here should either.
Shareable is listed beside Cloneable because the OwnedList family
constrains its element that way, and refusing it would exclude a container
from the interface over a contract the interface never uses.
kernel/src/interfaces.ev:521
Methods
METHOD iterator() RETURNS ReferenceIterator[T]
GROUP Collectors
kernel/src/interfaces.ev:163
INTERFACE Countable
Countable is an opt-in interface for any class that enumerates how many elements it holds.
kernel/src/interfaces.ev:250
Methods
METHOD size() RETURNS int64
METHOD isEmpty() RETURNS boolean
INTERFACE Iterator
Iterator OF T — forward-traversal cursor over a collection. Per spec §Iterator (L730+).
- hasNext() — TRUE if cursor has not reached the end
- next() — advances cursor and returns the new element; EMPTY when end is reached
- peek() — returns what next() would return, without advancing. Calling twice in a row returns the same value
- skip(n) — moves cursor forward by n positions; returns
the element at the new position, or EMPTY if end
is reached. skip(0) is equivalent to peek().
Parameter is unsigned: backward movement is
unavailable on Iterator OF T (forward-only
iterators have no notion of "previous"). Use
BidirectionalIterator OF T's skipBack(n) for
reverse traversal.
Iterator OF T — the iteration root. The only operation universal
to every iterator is hasNext(): no single advance form fits both
referenceable storage and by-value storage, so the advance methods
live on the two sub-interfaces below. The FOR / WHILE loop
machinery holds an Iterator and dispatches on which sub-interface
the concrete iterator implements — ReferenceIterator (collections,
referenceable storage) or ValueIterator (buffers, by-value storage).
The element is what is ITERATED, and
hasNext()uses it not at all — the qualifier saidT IS Countable, which asked the ELEMENT to have a size. So it admits every element any of its sub-interfaces admits (I.K.ix: an interface's qualifier may demand only what its own methods use): a plain CLASS (ObjectIterator OF Row— Cloneable/Shareable alone refused it at the kernel's own EXTENDS edge), any BLITTABLE value (ValueIterator), and the Cloneable/Shareable/primitive elementsReferenceIteratorhands out.
kernel/src/interfaces.ev:291
Methods
METHOD hasNext() RETURNS boolean
INTERFACE ObjectIterator
ObjectIterator OF T — extends Iterator with by-reference navigation
over a HEAP-CLASS element type. The object peer of ReferenceIterator:
where ReferenceIterator's bound admits only Cloneable primitives,
ObjectIterator admits any class, so a collection whose logical
element is a synthesized class instance (a per-position VIEW — e.g.
a DataFrame yielding a Row built from its stored columns) can be
FOR e IN coll-iterable. Because the source may not STORE the
element (it synthesizes it), the concrete iterator OWNS the current
element in an internal slot and hands back a non-owning REFERENCE
into that slot; the reference is valid until the next advance, on
which the slot is refreshed. The FOR-IN loop borrows it for the
iteration exactly as it borrows a ReferenceIterator's referent —
so next() lowers to REFERENCE T (a T*) on both this interface
and its implementers, with none of the value-form covariance seam.
kernel/src/interfaces.ev:434
Methods
MODIFY METHOD next() RETURNS | REFERENCE T
2.0 pipe-XOR shape: a successful navigation refreshes the
iterator's owned slot and populates value with a non-owning
reference into it; end-of-iteration populates s with FAILURE.
METHOD peek() RETURNS | REFERENCE T
peek is non-consuming: the reference to the current slot without advancing. Same pipe-XOR shape as next().
INTERFACE ReferenceIterator
ReferenceIterator OF T — extends Iterator with by-reference
navigation. Implemented by the collection iterators, whose backing
storage is referenceable: next() / peek() / skip() hand back a
non-owning reference into the source rather than a copy. Buffer
iterators (over by-value _cxx* storage) implement only the
value-form Iterator.
next/peek/skip hand back a REFERENCE and never clone, so Cloneable
was never used; Shareable joins it so the OwnedList family qualifies.
kernel/src/interfaces.ev:384
Methods
MODIFY METHOD next() RETURNS | REFERENCE T
2.0 pipe-XOR shape: a successful navigation populates value
with a non-owning reference into the source; end-of-iteration
or invariant violation populates s with FAILURE. The caller's
IF iter->next() THEN { binding REFERENCE T v =@ $RETURNED } ELSE { ... } binds the
populated slot.
METHOD peek() RETURNS | REFERENCE T
peek is non-PANICing and non-consuming: returns the reference at the current cursor without advancing. Same pipe-XOR shape as next().
MODIFY METHOD skip(uint64 n) RETURNS | REFERENCE T
INTERFACE Searchable
Searchable OF T — contents can be searched for a needle of the same
Text kind. find returns the match position; pipe-XOR FAILURE means
no match. Implemented by String and StringView — the view holds the
one canonical scan, and String forwards through a full-span view.
kernel/src/interfaces.ev:328
Methods
METHOD find(REFERENCE T needle) RETURNS | int64
INTERFACE ValueIterator
ValueIterator OF T — extends Iterator OF T with by-value navigation. Implemented by the buffer iterators, whose backing storage yields elements by value, not by reference: nextValue() / peekValue() / skipValue() hand back a copy of the element. The value-form mirror of ReferenceIterator.
kernel/src/interfaces.ev:406
Methods
MODIFY METHOD nextValue() RETURNS | T
2.0 pipe-XOR shape: a successful navigation populates value
with a copy of the element at the new cursor; end-of-iteration
populates s with FAILURE.
METHOD peekValue() RETURNS | T
peekValue is non-consuming: the value at the current cursor without advancing. Same pipe-XOR shape as nextValue().
MODIFY METHOD skipValue(uint64 n) RETURNS | T
Copying and ownership
INTERFACE Cloneable
Cloneable — per. A class implementing Cloneable opts in to deep-copy semantics: := on instances calls clone(); the *Copy family of collection methods clones each class-typed element through this interface.
Implementations declare their own concrete return type — Envzn's interface satisfaction rule accepts any return type that itself implements Cloneable (covariant-return-via-subtype), so:
CLASS Person IMPLEMENTS Cloneable { METHOD clone() RETURNS Person { Person p := CREATE Person(.age) RETURN (p) } }
...satisfies the contract without any cast.
An AUTO clone is the other form, and it declares NO return type: the
compiler supplies the body AND the concrete return type, so writing
RETURNS on one is E7029 (auto-clone-with-returns).
CLASS Point IMPLEMENTS Cloneable {
AUTO METHOD clone() { } // generated; never RETURNS Point
}
kernel/src/interfaces.ev:205
Methods
METHOD clone() RETURNS Cloneable
GROUP Inoperative
GROUP Inoperative — the types whose values generic code may not
operate on: no clone, no copy, no iteration over the payload. Today's
sole member is opaque (I.D.v), whose payload type is erased, so no
method dispatch on it is well-defined. A generic kernel container
(Box, Array, ...) tests membership on its type parameter:
WHEN T IS Inoperative { /* opt out */ } ELSE { /* the general path */ }
A GROUP, not an interface: it states its members by name, it needs no method (Envzn forbids an empty interface, E6001), and membership is a compile-time fact read off this declaration, so every backend decides it the same way.
kernel/src/interfaces.ev:368
Equality, ordering and hashing
INTERFACE Comparable
Comparable[T] — type defines a strict less-than ordering. Extends Equatable[T]: a type that is comparable is necessarily equatable (otherwise sorted-and-equal-to checks can't compose).
Required for any T used in:
- SortedList[T] (insert position determined by isLessThan)
- Array[T]->sort() (insertion-sort or quicksort comparator)
- any future ordered collection
The implementation MUST satisfy a strict total order:
- Irreflexive — a.isLessThan(a) is always FALSE.
- Antisymmetric — if a.isLessThan(b) then NOT b.isLessThan(a).
- Transitive — if a.isLessThan(b) and b.isLessThan(c),
then a.isLessThan(c).
- Trichotomous (consistent with Equatable) — for every
pair, exactly one of a.isLessThan(b), b.isLessThan(a),
or a.isEqualTo(b) is TRUE.
The kernel provides built-in Comparable behaviour for primitive
numerics (int8..int64, uint8..uint64, float32, float64,
byte, char) and String (lexicographic). boolean is also
comparable (FALSE < TRUE). Class types must declare
IMPLEMENTS Comparable[K] and provide isLessThan(K) and
isEqualTo(K) methods explicitly.
isLessThanOrEqual, isGreaterThan, isGreaterThanOrEqual are
derivable and not part of this interface; the canonical method
is isLessThan. Callers compose: NOT a.isLessThan(b) is
"a >= b", b.isLessThan(a) is "a > b", etc.
kernel/src/interfaces.ev:557
Methods
METHOD isLessThan(REFERENCE T other) RETURNS boolean
INTERFACE Equatable
Equatable[T] — type can compare itself to another instance of the same type for value equality. Parameterised over T to pin the comparison type at the implementation site:
CLASS Token IMPLEMENTS Equatable[Token] {
METHOD isEqualTo(Token other) RETURNS boolean { ... }
}
Equatable is the contract Dictionary uses to resolve hash collisions and Set uses for membership. Required alongside Hashable for any class type used as a Dictionary key.
Implementations must be:
- Reflexive — a.isEqualTo(a) is always TRUE.
- Symmetric — a.isEqualTo(b) iff b.isEqualTo(a).
- Transitive — if a.isEqualTo(b) and b.isEqualTo(c),
then a.isEqualTo(c).
- Consistent with Hashable — if a.isEqualTo(b), then
a.hash() == b.hash(). (The reverse need not hold; hash
collisions on equal-by-isEqualTo objects break Dictionary.)
Built-in for primitives and String, same as Hashable.
kernel/src/interfaces.ev:319
Methods
METHOD equals(REFERENCE T other) RETURNS boolean
GROUP HashKey
kernel/src/interfaces.ev:158
INTERFACE Hashable
Hashable — type can produce a stable hash code of itself.
Returned value is uint64 per spec §Hashable and KeyHasher
(CONSTITUTION L3611). Implementing classes are eligible for use
as Dictionary[K: V] keys (paired with Equatable[K], below) and
Set[T] elements.
The hash MUST be: - Deterministic — equal objects (per Equatable.isEqualTo) must produce equal hashes. Calling hash() on the same value twice must yield the same result. - Pure — no observable side effects, no I/O, no mutation of SELF or any reachable state.
The kernel provides built-in Hashable behaviour for primitives
(int8..int64, uint8..uint64, float32, float64, byte,
char, boolean) and String — those types do not need to
declare IMPLEMENTS Hashable explicitly. Dictionary[K: V] uses
the built-in path automatically when K is one of those.
kernel/src/interfaces.ev:484
Methods
METHOD hash() RETURNS uint64
GROUP Incomparable
GROUP Incomparable — the primitives with no equality: opaque (move-only, a
tagged payload), and the UNSAFE.* handles, whose == would compare
addresses, which says nothing about what they hold. Comparing two arrays of
one is a compile error (E5026), never a runtime answer.
kernel/src/interfaces.ev:112
GROUP OperatorEquatable
GROUP OperatorEquatable — the primitives that compare with == / !=, and
only that way. A kernel body comparing elements of a type parameter picks its
comparison by group (NativeArray.equals): this group takes the operator,
Equatable takes ->equals(), and Incomparable has no equality at all.
decimal128 also has ==, but it is Equatable and compares through its exact equals, so it is not a member: one type, one way.
kernel/src/interfaces.ev:98
GROUP WordKey
GROUP WordKey — a primitive whose value IS an integer bit-pattern, so a
hasher body may reduce it to its hash word with uint64 v = #key (I.F.ii(a):
the value mod 2^64) and nothing about the value domain changes. It is
exactly the operand set # accepts (E2153).
FastIntHasher and InlineIntHasher were qualified PRIMITIVE(EXCEPT
opaque, boolean, number, complex) while their bodies are a bare
uint64 v = key — which TRUNCATES for float32/float64, is forbidden outright
for decimal128 (E2121 — decimal never mixes), and names a FOREIGN-only type
for the C.* four. The constraint admitted types the body could not honour.
This is the set it can.
int128/uint128 ARE members, and they are the one case where the reduction is lossy: the high 64 bits are dropped, so two keys differing only above bit 63 hash alike. That is a WEAK hash, not a wrong one — Equatable still separates them on lookup, and taking low bits is an ordinary hash fold. A float is excluded for the different reason that its bits are not a value: the same number has several encodings, so # on it would not be a fold but a reinterpretation.
kernel/src/interfaces.ev:137
Text I/O
INTERFACE Printable
Printable — type can render itself directly to stdout.
Distinct from Readable — Readable produces a String for the caller to do something with; Printable is the convenience for types that own their own output side effects (e.g. a complex renderer that writes structured output to multiple lines).
Most types should implement Readable and let callers route the output. Printable is for cases where producing the intermediate String would be wasteful (e.g. large structured dumps).
kernel/src/interfaces.ev:644
Methods
METHOD print() RETURNS void
INTERFACE Readable
Readable — a byte source: the counterpart of Writable. The single
operation is read — drain the source into an storage char8[512+]
of whatever it had. File, Socket, and the Stdio stdin source
implement it, so code can ask of any of them "can I read this?"
the same way Writable answers "can I write it?".
read returns the bytes it managed to produce as a char8[512+]
storage value — empty when the source has none, populated through
to end-of-input otherwise. The FAILURE status is reserved for a
genuine read error, not for a short or empty read. The caller can
build a ByteBuffer or DynamicByteBuffer from the returned
storage when a wrapper is needed (§21).
Spec reference: stdio-spec.md §6.
kernel/src/interfaces.ev:627
Methods
MODIFY METHOD read() RETURNS | binary[]
GROUP Text
kernel/src/interfaces.ev:167
INTERFACE Writable
Writable — a byte sink. The single operation is write: hand it a
ByteBuffer and it delivers every byte or fails. Implemented by the
Stdio stdout/stderr sinks, by File, and by Socket — so a rendered
String (from a Formatter) can reach any of them through one
uniform call.
All-or-nothing: a short OS write is retried internally, so the outcome is SUCCESS — every byte written, count returned — or a FAILURE status. There is no partial write.
THE EXTENT IS THE ARRAY'S OWN LENGTH — there is deliberately no
length parameter. The old shape
write(content, length) passed the caller's integer straight to
POSIX write, which reads that many bytes from the base pointer:
write(twoByteBuffer, 65536) wrote 64 KB of live heap — including a
pointer — to disk, with no diagnostic at any phase. CWE-126, and
severity 10 against I.A's memory-safe floor.
It was also redundant. read/readAt already return a char8[]
whose .length IS the valid extent, so the class conveyed extent by
array length in one direction and by a separate integer in the other.
Three of the four call sites in the whole corpus passed a value equal
to the array's length anyway.
To write PART of a buffer, take a view (ByteBufferView is
REFERENCE char8[] source + start + length) or pass a right-sized
array. A lone length could only ever express a prefix — it has no
offset — so it was never the right tool for a slice.
Spec reference: stdio-spec.md §6.
kernel/src/interfaces.ev:866
Methods
MODIFY METHOD write(REFERENCE binary[] content) RETURNS | int64
Views
INTERFACE View
View — the non-owning window itself. Minimal base contract; the element-typed operations (operator[], iterator, find via Searchable, copy) live on the concrete view (StringView). Kept deliberately minimal so a future N-D view tier is not constrained by 1-D shape. Declared before Viewable because Viewable.view() references it.
kernel/src/interfaces.ev:337
Methods
METHOD length() RETURNS int64
INTERFACE Viewable
Viewable — a source that yields a non-owning, bounded View into its
own storage without copying. view(start, length) windows over
[start, start+length). The return type is the base View; an
implementer narrows it covariantly to its concrete view (String
returns StringView). This is the 1-D / linear tier (String now;
ArrayView / byte-buffer views later) — the N-D strided views the
Data module needs are a separate, related contract.
kernel/src/interfaces.ev:348
Methods
METHOD view(int64 start, int64 length) RETURNS View