Skip to main content

List Library (List)

Linked to the list type — Collections covers the core operations already; this page is the complete reference.

Query​

List::len(array: list) -> int​

list-len.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  pln(array.len());
}
Output

List::empty(array: list) -> bool​

list-empty.stofPlayground ↗
#[main]
fn main() {
  const array = [1];
  pln(array.empty());
}
Output

List::any(array: list, func?: fn) -> bool​

Without a function: does the list have any values? With one: does it return true for any value?

list-any.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  pln(array.any());
  pln(array.any((x: int): bool => x > 2));
}
Output

List::contains(array: list, value: unknown) -> bool​

list-contains.stofPlayground ↗
#[main]
fn main() {
  const array = [1];
  pln(array.contains(1));
}
Output

List::index_of(array: list, v: unknown) -> int​

-1 if not found.

list-index-of.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  pln(array.index_of(2));
}
Output

List::is_uniform(array: list) -> bool​

If every value has the exact same specific type, will return that type — prototype inheritance isn't considered. Otherwise, returns null.

list-is-uniform.stofPlayground ↗
#[main]
fn main() {
  const array = ["hi", 'true'];
  pln(array.is_uniform());
}
Output

Access​

List::at(array: list, index: int) -> unknown​

&array[i] for a reference, so mutating the result mutates the list itself.

list-at.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  let v = &array[1];
  v = 5;
  pln(array);
}
Output

List::front(array: list) -> unknown​

list-front.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2];
  pln(array.front());
}
Output

List::back(array: list) -> unknown​

list-back.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2];
  pln(array.back());
}
Output

Modify​

List::push_back(array: list, ..) -> void​

Takes any number of values.

list-push-back.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  array.push_back(4, 5);
  pln(array);
}
Output

List::push_front(array: list, ..) -> void​

list-push-front.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  array.push_front(4, 5);
  pln(array);
}
Output

List::pop_back(array: list) -> unknown​

list-pop-back.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  pln(array.pop_back(), ' ', array);
}
Output

List::pop_front(array: list) -> unknown​

list-pop-front.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  pln(array.pop_front(), ' ', array);
}
Output

List::insert(array: list, index: int, val: unknown) -> void​

list-insert.stofPlayground ↗
#[main]
fn main() {
  const array = [2, 1];
  array.insert(1, 3);
  pln(array);
}
Output

List::replace(array: list, index: int, val: unknown) -> unknown​

Returns the old value.

list-replace.stofPlayground ↗
#[main]
fn main() {
  const array = [2, 1];
  pln(array.replace(1, 4), ' ', array);
}
Output

List::append(array: list, other: list) -> void​

other is left unmodified.

list-append.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  array.append([4, 5]);
  pln(array);
}
Output

List::clear(array: list) -> void​

list-clear.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  array.clear();
  pln(array);
}
Output

List::join(array: list, sep: str) -> str​

list-join.stofPlayground ↗
#[main]
fn main() {
  const array = ["hello", "world"];
  pln(array.join(", "));
}
Output

Removing​

List::remove(array: list, index: int) -> unknown​

Returns the removed value, or null if the index was out of bounds.

list-remove.stofPlayground ↗
#[main]
fn main() {
  const array = [1];
  pln(array.remove(0), ' ', array.empty());
}
Output

List::remove_first(array: list, val: unknown) -> unknown​

list-remove-first.stofPlayground ↗
#[main]
fn main() {
  const array = [2, 1, 1, 2];
  pln(array.remove_first(2), ' ', array);
}
Output

List::remove_last(array: list, val: unknown) -> unknown​

list-remove-last.stofPlayground ↗
#[main]
fn main() {
  const array = [2, 1, 1, 2];
  pln(array.remove_last(2), ' ', array);
}
Output

List::remove_all(array: list, val: unknown) -> bool​

Returns whether anything was actually removed.

list-remove-all.stofPlayground ↗
#[main]
fn main() {
  const array = [2, 1, 1, 2];
  pln(array.remove_all(2), ' ', array);
}
Output

Transform​

These call a function for each value, in order, and return a new list (the original isn't changed).

List::map(array: list, func: fn) -> list​

The result of the function for each value. With an async function, the list holds its promises: await the list.

list-map.stofPlayground ↗
#[main]
fn main() {
  const prices = [10, 20, 30];
  pln(prices.map((p: int): float => p * 1.2));
}
Output

List::filter(array: list, func: fn) -> list​

The values the function returns true for.

list-filter.stofPlayground ↗
#[main]
fn main() {
  const orders = [120, 40, 300, 75];
  pln(orders.filter((total: int): bool => total >= 100));
}
Output

Sort & Reverse​

List::sort(array: list) -> void​

list-sort.stofPlayground ↗
#[main]
fn main() {
  const array = [2, 1, 4, 3];
  array.sort();
  pln(array);
}
Output

List::sort_by(array: list, func: fn) -> void​

The comparator returns negative/zero/positive, same convention as everywhere else. The sort is stable (values that compare equal keep their order), and an error in the comparator fails the sort. Written as a single ternary expression here rather than a chain of bare if statements — if can't produce a value on its own (see Control Flow), so a chain of them with no else wouldn't actually control the sort order the way it looks like it would.

list-sort-by.stofPlayground ↗
#[main]
fn main() {
  const array = [2, 1, 4, 3];
  array.sort_by((a: int, b: int): int => a < b ? 1 : (a > b ? -1 : 0));
  pln(array);
}
Output

List::reverse(array: list) -> void​

In place.

list-reverse.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  array.reverse();
  pln(array);
}
Output

List::reversed(array: list) -> list​

Returns a new reversed list, leaving the original untouched.

list-reversed.stofPlayground ↗
#[main]
fn main() {
  const array = [1, 2, 3];
  const other = array.reversed();
  pln(array, ' ', other);
}
Output

Convert​

List::to_uniform(array: list, type: str) -> void​

Casts every value to the given type in place — throws if any value can't be cast.

list-to-uniform.stofPlayground ↗
#[main]
fn main() {
  const array = [1, "hi", true];
  array.to_uniform("str");
  pln(array);
}
Output