class List

pub class List<T> :: [IndexSet<int>, Length, Iterable, AsSlice<T>]

Conforms to IndexSet<int>, Length, Iterable, AsSlice<T>, FromArrayLiteral<T>, Equatable, Debug, Display, FromIterator<T>, Contains<T>, Clone.

A growing array: its elements in order, indexed from 0.

list[i] and list[i] = v work as on an array; list[a..b] is a view of the elements, as asSlice()[a..b]. When full, the buffer doubles, so push is amortized constant time. Not safe across threads.

Panics

list[i] and list[i] = v panic outside 0 ≤ i < length().

Methods

pub static fn new(): List<T>

Creates an empty list.

pub static fn withCapacity(n: int): List<T>

Creates an empty list with room for n elements before it grows.

The room is allocated at the first push.

Panics

When n is negative.

pub static fn of(xs: T[]): List<T>

Creates a list of the array's elements, copied.

pub fn length(): int

Returns how many elements it holds.

pub fn isEmpty(): bool

Returns whether it holds no elements.

pub fn index(i: int): T

Returns the element at i; this is list[i].

Panics

Outside 0 ≤ i < length(), with LYR-RT0003.

pub mut fn setIndex(i: int, v: T): void

Replaces the element at i with v; this is list[i] = v.

Panics

Outside 0 ≤ i < length(), with LYR-RT0003.

pub fn get(i: int): ?T

Returns the element at i, or null outside 0 ≤ i < length().

Examples

import std.io { println };

let xs = List.of([10, 20]);
println(xs.get(1) ?? -1);
println(xs.get(2) ?? -1);

20
-1

pub fn asSlice(): Slice<T>

Returns a view of the elements in the list's buffer.

The members of views reach the elements in place: sorting the view sorts the list. A push past the room moves the list to a new buffer; a view taken before stays on the old one.

pub fn toArray(): T[]

Returns the elements copied into a new array, in order.

pub mut fn push(v: T): void

Appends v at the end.

Amortized constant time: a full buffer is replaced by one twice its size.

Examples

import std.io { println };

let xs = List.of([1, 2]);
xs.push(3);
println(xs.length());

The element has the list's type:

Does not compile — the compiler reports LYR-SEM0001

fn main(): void {
    let xs = List.of([1, 2]);
    xs.push("three");
}

error[LYR-SEM0001]: cannot assign 'string' to 'int'
 --> src/main.lyr:3:13
  |
3 |     xs.push("three");
  |             ^^^^^^^

pub mut fn pushAll(xs: T[]): void

Appends every element of xs at the end, in order.

pub mut fn pop(): ?T

Removes and returns the last element, or null where there is none.

pub mut fn insert(i: int, v: T): void

Inserts v at i, moving the elements from i on one place towards the end.

Takes time linear in the number of elements moved.

Panics

When i is outside 0 ≤ i ≤ length().

pub mut fn removeAt(i: int): T

Removes and returns the element at i, moving those after it one place towards the front.

Takes time linear in the number of elements moved.

Panics

When i is outside 0 ≤ i < length(), with LYR-RT0003.

pub mut fn removeWhere<E :: [Error]>(p: fn(T) -> bool throws E): int throws E

Removes the elements for which p holds, keeping the others in order, and returns how many were removed.

One pass, linear time.

Errors

Throws what p throws. The removal stops there: the elements already decided are removed or kept, and the rest stay in the list in their order.

pub mut fn clear(): void

Removes every element; the allocated room stays.

pub mut fn truncate(n: int): void

Keeps the first n elements and removes the rest.

An n at or past the length keeps all.

Panics

When n is negative.

pub mut fn swap(i: int, j: int): void

Exchanges the elements at i and j.

Panics

When i or j is outside 0 ≤ i < length().

pub fn iter(): ListIter<T>

Returns an iterator over the elements, front to back.

Panics

The next pull panics (LYR-RT0016) after a push, a pop or another change of the length while the iterator walks.

pub static fn from<I :: [Iterator<Item = T>]>(items: I): List<T> throws I.Error

Creates a list of the values of an iterator, in order: List.from(words.iter()).

Errors

Throws what a pull of items throws.

pub mut fn shrinkToFit(): void

Shrinks the allocated room to the elements: a buffer of length() slots.

A view taken before keeps the buffer it was taken of.

pub mut fn remove(x: T): bool

Removes the first element equal to x and returns whether there was one.

pub mut fn dedup(): void

Removes consecutive repeated elements, keeping the first of each run of equal ones.

static fn fromLiteral(items: T[]): List<T>

fn equals(o: List<T>): bool

fn debug(): string

fn debugTo(out: StringBuilder): void

fn show(): string

fn showTo(out: StringBuilder): void

static fn fromIter<I :: [Iterator<Item = T>]>(it: I): List<T> throws I.Error

fn contains(x: T): bool

Returns whether an element equals x; this is x in list.

fn clone(): List<T>