Axle v0.22.0
Package

std/collections

std/collections — the collections framework.

The generic Iterator / Collection / List / Set / Map
contracts the concrete classes fulfil. Each implementation lives in
its own file under std/collections/ and resolves by bare name
(use std::collections::ArrayList; etc.) regardless of file:

• ArrayList<T> → arraylist.axle (growable array)
• HashSet<T> → hashset.axle (SwissTable set)
• HashMap<K, V> → hashmap.axle (SwissTable map)

The traits below name the shared contracts; a class opts into one
with : Trait and the conformance check enforces it.

Iterator and Iterable are the two protocols for (x of it) walks:
a type that declares the methods of either is iterable, whether or not
it lists the trait, and ArrayList, HashSet and HashMap declare the
methods of Iterable.

T trait Iterator<T>

One-directional cursor over a sequence of T. Drive it with the
hasNext() guard before each next(); the two together walk the
elements exactly once, in order. for (x of it) writes that loop.

TypeMethod and description
bool
hasNext(self) : bool True while at least one element remains to be returned.
T
next(self) : T Advance and return the next element. Call only after hasNext().

Method detail

#hasNext

hasNext(self) : bool

True while at least one element remains to be returned.

#next

next(self) : T

Advance and return the next element. Call only after hasNext().

T trait Iterable<T>

A collection of T that for (x of c) walks by slot, leaving the cursor
in the loop. A slot is a position in the collection's own storage; the
loop searches from where the previous slot ended, so each element is read
against the collection as it is at that moment.

TypeMethod and description
i64
nextSlot(self, start : i64) : i64 The first live slot at or after start, or a negative number when
none remains.
T
elementAt(self, slot : i64) : T The element held in slot, a value nextSlot returned.

Method detail

#nextSlot

nextSlot(self, start : i64) : i64

The first live slot at or after start, or a negative number when
none remains.

#elementAt

elementAt(self, slot : i64) : T

The element held in slot, a value nextSlot returned.

T trait Collection<T>

The root contract every collection of T honours: membership,
cardinality, and bulk mutation. List and Set refine it with
ordering / uniqueness guarantees.

TypeMethod and description
bool
add(self, element : T) : bool Add element; returns whether the collection changed.
bool
remove(self, element : T) : bool Remove one occurrence of element; returns whether it was present.
void
clear(self) : void Drop every element, leaving the collection empty.
bool
contains(self, element : T) : bool True when an equal element is held.
i64
size(self) : i64 Live element count.
bool
isEmpty(self) : bool True when no elements are held.

Method detail

#add

add(self, element : T) : bool

Add element; returns whether the collection changed.

#remove

remove(self, element : T) : bool

Remove one occurrence of element; returns whether it was present.

#clear

clear(self) : void

Drop every element, leaving the collection empty.

#contains

contains(self, element : T) : bool

True when an equal element is held.

#size

size(self) : i64

Live element count.

#isEmpty

isEmpty(self) : bool

True when no elements are held.

T trait List<T>

An ordered, index-addressable sequence of T. Positions are dense
0 .. size; ArrayList<T> is the concrete implementation.

TypeMethod and description
bool
add(self, element : T) : bool Append element to the end; always changes the list.
T
get(self, index : i64) : T Element at index.
T
set(self, index : i64, element : T) : T Overwrite the element at index.
T
removeAt(self, index : i64) : T Remove the element at index, shifting later elements down one.
i64
indexOf(self, element : T) : i64 Position of the first element equal to element.
bool
contains(self, element : T) : bool True when an equal element is held.
i64
size(self) : i64 Live element count.
bool
isEmpty(self) : bool True when the list is empty.
void
clear(self) : void Drop every element.

Method detail

#add

add(self, element : T) : bool

Append element to the end; always changes the list.

#get

get(self, index : i64) : T ! IndexOutOfBoundsException

Element at index.

Throws
IndexOutOfBoundsException when index is negative or >= size.

#set

set(self, index : i64, element : T) : T ! IndexOutOfBoundsException

Overwrite the element at index.

Returns the value previously held there.
Throws
IndexOutOfBoundsException when index is out of range.

#removeAt

removeAt(self, index : i64) : T ! IndexOutOfBoundsException

Remove the element at index, shifting later elements down one.

Returns the removed element.
Throws
IndexOutOfBoundsException when index is out of range.

#indexOf

indexOf(self, element : T) : i64

Position of the first element equal to element.

Returns its index, or -1 if absent.

#contains

contains(self, element : T) : bool

True when an equal element is held.

#size

size(self) : i64

Live element count.

#isEmpty

isEmpty(self) : bool

True when the list is empty.

#clear

clear(self) : void

Drop every element.

T trait Set<T>

An unordered collection of distinct T — no element appears twice.
HashSet<T> is the concrete implementation.

TypeMethod and description
bool
add(self, element : T) : bool Add element if absent; returns true only on a genuine insert.
bool
remove(self, element : T) : bool Remove element; returns whether it was present.
bool
contains(self, element : T) : bool True when an equal element is a member.
i64
size(self) : i64 Number of distinct elements.
bool
isEmpty(self) : bool True when the set is empty.
void
clear(self) : void Drop every element.

Method detail

#add

add(self, element : T) : bool

Add element if absent; returns true only on a genuine insert.

#remove

remove(self, element : T) : bool

Remove element; returns whether it was present.

#contains

contains(self, element : T) : bool

True when an equal element is a member.

#size

size(self) : i64

Number of distinct elements.

#isEmpty

isEmpty(self) : bool

True when the set is empty.

#clear

clear(self) : void

Drop every element.

T trait Map<K, V>

An association of distinct keys K to values V. Lookup throws on a
miss rather than returning a sentinel, since V is non-nullable;
HashMap<K, V> is the concrete implementation.

TypeMethod and description
void
put(self, key : K, value : V) : void Insert key, or overwrite its existing value with value.
V
get(self, key : K) : V Value bound to key.
bool
remove(self, key : K) : bool Remove the entry for key; returns whether it was present.
bool
containsKey(self, key : K) : bool True when key has a bound value.
i64
size(self) : i64 Number of entries.
bool
isEmpty(self) : bool True when the map holds no entries.
void
clear(self) : void Drop every entry.

Method detail

#put

put(self, key : K, value : V) : void

Insert key, or overwrite its existing value with value.

#get

get(self, key : K) : V ! NoSuchElementException

Value bound to key.

Throws
NoSuchElementException when key is absent.

#remove

remove(self, key : K) : bool

Remove the entry for key; returns whether it was present.

#containsKey

containsKey(self, key : K) : bool

True when key has a bound value.

#size

size(self) : i64

Number of entries.

#isEmpty

isEmpty(self) : bool

True when the map holds no entries.

#clear

clear(self) : void

Drop every entry.