Library / Collections / Dictionaries / Dictionary
Dictionary
Dictionary is a pure INTERFACE, not a concrete class, and is no longer special-cased by the compiler. It is an ordinary parametric interface the compiler treats like any other.
Methods 12
METHOD clone() RETURNS Dictionary[K, V, H]reads
Deep copy. (Cloneable contract; covariant return — an impl returns its own concrete type.)
METHOD iterator() RETURNS ReferenceIterator[K]reads
Forward-only iterator over the keys. FOR/IN over a Dictionary visits each key once.
METHOD keys() RETURNS LinkedList[K]reads
Snapshot of all keys in a fresh LinkedList (each key cloned).
METHOD isEmpty() RETURNS booleanreads
check if the dictionary is empty
METHOD size() RETURNS int64reads
Number of key→value pairs currently stored. All three impls already
provide it; declaring it here makes it callable through a Dictionary
interface handle.
MODIFY METHOD clear() RETURNS voidmodifies
MODIFY METHOD insert(K key, V value) RETURNS STATUSmodifies
insert (key, value). BOTH are MOVEd in (consumed) — the dictionary
owns what it stores, so there is nothing for it to clone. Replacing an
existing key destroys the old value and leaves the count unchanged.
SUCCESS always (FAILURE only on an EMPTY key/value where the type is
Cloneable). Use insertCopy to keep your own key and value.
MODIFY METHOD insertCopy(REFERENCE K key, REFERENCE V value) RETURNS STATUSmodifies
Deep-copy insert — both key and value stay valid for the caller.
METHOD lookup(REFERENCE K key) RETURNS | MUTABLE REFERENCE Vreads
Lookup — a reference into the stored value, or FAILURE if the key is absent. Gate on STATUS, not on the returned V. A borrow-propagating ("mirror") accessor: the returned reference mirrors the receiver's mutability — a mutable dictionary yields a MUTABLE REFERENCE (modify the value in place), a const one a read-only REFERENCE. Valid while the dictionary is not mutated (iterator mutation lock).
There is deliberately NO value-cloning lookup: borrowing is the default
and owning is explicit. To own a copy, clone the borrow; to own the
value itself, remove it.
METHOD lookupFast(REFERENCE K key) RETURNS booleanreads
Allocation-free lookup — found plus the value, no pipe and no STATUS.
This is not a faster lookup; it is a lookup with a different COST on
the miss. lookup builds a FAILURE("...key not found") when the key
is absent, so a loop that misses once per distinct key — a group-by, a
join, a dedupe — allocates a formatted String per miss, a cost the pipe
hides completely at the call site. Every implementation already knows
whether the key is present before it decides what to return, so making
this part of the interface costs nothing and is what lets a consumer
stay on the interface instead of reaching for the concrete class.
On a miss value is the type's absent form (EMPTY for a class V, zero
for a primitive) and MUST NOT be read: found is the only valid
discriminator. C# spells the same contract TryGetValue.
MODIFY METHOD remove(REFERENCE K key) RETURNS | Kmodifies
remove — MOVES both halves out, or FAILURE if the key is absent. Nothing is cloned: the stored key and value are handed to the caller rather than copied and destroyed. The returned key is the STORED one, which is equal to — but not necessarily the same object as — the probe key, which is why it is worth returning.
METHOD contains(REFERENCE K key) RETURNS booleanreads
contains - like lookup() but only returns a boolean if the key-value pair is found