list¶

Reductions, slicing, and higher-order methods on arrays.

The module is part of the prelude, so every method here works on any array with no import line: [1, 2, 3].sum(), xs.map(f). The methods are defined in an impl list block; see methods for how impl blocks on the built-in types resolve.

The helpers are polymorphic through compile-time monomorphisation: one definition specialises to whatever element type the call site uses. A lookup that may find nothing (first, last, min, max, find) answers an Option: Some of the element, or None for an empty list or no match. The reductions sum and product read their seed from the first element, so they need a non-empty list.

The module is pure candela, so it compiles into a .cdlb artifact and runs under candela-vm with no dynamic library. It builds on the built-in array methods (len, push, contains, index_of, sort, and the rest), which are listed in built-in functions.

Element access¶

first¶

arr.first()

Returns: Some of the element at index 0, or None for an empty list.

last¶

arr.last()

Returns: Some of the element at index arr.len() - 1, or None for an empty list.

is_empty¶

arr.is_empty()

Returns: a bool, true when arr has no elements.

count¶

arr.count(value)

value: an element to look for.
Returns: the number of elements equal to value, as an int.

Reductions¶

sum¶

arr.sum()

Returns: the elements combined left to right with +.
Raises: index_out_of_bounds on an empty list.

The element type only has to support +, so a list of strings sums to their concatenation.

product¶

arr.product()

Returns: the elements combined left to right with *.
Raises: index_out_of_bounds on an empty list.

min¶

arr.min()

Returns: Some of the smallest element, compared with <, or None for an empty list.

The element type has to be one < orders: int, float, or string. A list of strings answers with the first one in byte order, the same order sort uses; see operators.

max¶

arr.max()

Returns: Some of the largest element, compared with >, or None for an empty list.

The element type has to be one > orders, as for min.

Slicing and reshaping¶

take¶

arr.take(n)

n: an int.
Returns: a new list of the first n elements, or a copy of the whole list when n exceeds the length. An empty list gives an empty list.

drop¶

arr.drop(n)

n: an int.
Returns: a new list of every element after the first n, and an empty list when n reaches or exceeds the length.

chunk¶

arr.chunk(size)

size: an int.
Returns: a new list of consecutive sub-lists of at most size elements. The final chunk is shorter when the length is not a multiple of size. An empty list gives an empty result.

fn main() {
    print([1, 2, 3, 4, 5].chunk(2));
}

unique¶

arr.unique()

Returns: a new list with duplicate elements removed, keeping first-seen order. An empty list returns unchanged.

Higher-order helpers¶

Each of these takes a function value. Pass a named function or an anonymous one; see functions.

map¶

arr.map(f)

f: takes one element, returns the mapped value.
Returns: a new list of the results, in order.

filter¶

arr.filter(f)

f: takes one element, returns a bool.
Returns: a new list of the elements for which f is true, in order.

reduce¶

arr.reduce(init, f)

init: the starting accumulator.
f: takes the accumulator and an element, returns the new accumulator.
Returns: the accumulator after folding left to right. init on an empty list.

fn main() {
    let xs = [1, 2, 3, 4];
    print(xs.reduce(0, fn(acc, x) => acc + x));
}

each¶

arr.each(f)

f: takes one element; its result is discarded.
Returns: nothing. Call it for the side effect.

find¶

arr.find(f)

f: takes one element, returns a bool.
Returns: Some of the first element for which f is true, or None when none match.

The position of a value is the built-in arr.index_of(x), listed in built-in functions. find with an argument that is not a function is a compile error naming it.

any¶

arr.any(f)

f: takes one element, returns a bool.
Returns: true when f holds for at least one element. False on an empty list.

all¶

arr.all(f)

f: takes one element, returns a bool.
Returns: true when f holds for every element. True on an empty list.

sort_by¶

arr.sort_by(less)

less: takes two elements, returns true when the first comes before the second.
Returns: a new sorted list; arr is left unchanged.

A stable insertion sort. Use it when you need a custom order or an untouched input; the built-in arr.sort() sorts ints, floats, and strings ascending in place.

fn main() {
    let xs = [3, 1, 2];
    print(xs.sort_by(fn(a, b) => a > b));
    print(xs);
}