prelude: lists
Functions on lists
Functions on list(a). They are attached definitions on list, so xs \map(f) resolves to list.map without qualification when xs is a list, and are in the prelude, so no import is needed. list.groupBy, which gives a map, is on the maps and sets page.
Since lists are immutable, every function that transforms a list gives back a new one. When nothing else refers to the list you transform, the new list may be built in the old one’s memory: list.map rewrites its cells in place (see Reference counting).
Each of them is stack-safe, and works on a list of any length without running out of stack: it walks the list with tail calls, and one that builds a list builds it in reverse and reverses it at the end.
def scores = [3, 8, 1, 8, 5]
println(scores \list.filter { > 2 } \list.map { * 10 })
println(scores \list.distinct \list.sort)
println(scores \list.fold(0) { + })
-- [30, 80, 80, 50]
-- [1, 3, 5, 8]
-- 25
Reference
list.toList
def list.toList: list(a) -> list(a)
xs itself: a list is already one. With it, code written over any collection’s toList works
for a list too.
list.fromList
def list.fromList: list(a) -> list(a)
xs itself: a list is already one. With it, code written over any collection’s fromList works
for a list too.
list.fold
def list.fold: [c] list(a), b, ([c] (b, a) -> b) -> b
step applied to initial and the first element, then to that result and the second, and so on.
list.reduce
def list.reduce: [c] list(a), ([c] (a, a) -> a) -> #some(a) | #none
The elements of xs combined with f, in order, starting from the first: [1, 2, 3, 4, 5] \list.reduce { * } is #some(120), and an empty list, having no first element, gives #none.
To start from another value, use list.fold; for a total, list.sum or list.product.
list.reverse
def list.reverse: list(a) -> list(a)
The elements in reverse order.
list.length
def list.length: list(a) -> int
The number of elements.
list.sum
def list.sum: [Add(a)] list(a) -> a
The elements added together: [1, 2, 3] \list.sum is 6, and the sum of no elements is zero.
list.product
def list.product: [Num(a)] list(a) -> a
The elements multiplied together: [1, 2, 3, 4] \list.product is 24, and the product of no
elements is 1.
list.isEmpty
def list.isEmpty: list(a) -> bool
Whether there are no elements.
list.count
def list.count: [c] list(a), ([c] a -> bool) -> int
The number of elements test holds for.
list.head
def list.head: list(a) -> #some(a) | #emptyList
The first element, or #emptyList.
list.last
def list.last: list(a) -> #some(a) | #emptyList
The last element, or #emptyList.
list.at
def list.at: list(a), int -> #some(a) | #notFound
The element at position index, counting from 0, or #notFound when index is negative or past
the end. It walks to the element, in time proportional to index.
list.contains
def list.contains: [Eq(a)] list(a), a -> bool
Whether any element is equal to x. Elements are compared with ==, by their structure.
list.indexOf
def list.indexOf: [Eq(a)] list(a), a -> #some(int) | #notFound
The position of the first element equal to x, counting from 0, or #notFound. Elements are
compared with ==, by their structure.
list.findIndex
def list.findIndex: [c] list(a), ([c] a -> bool) -> #some(int) | #notFound
The position of the first element matches holds for, counting from 0, or #notFound.
list.map
def list.map: [c] list(a), ([c] a -> b) -> list(b)
f applied to each element, in order. Stack-safe: it works on a list of any length.
list.mapIndexed
def list.mapIndexed: [c] list(a), ([c] (int, a) -> b) -> list(b)
f applied to each element’s position, counting from 0, and the element, in order. Stack-safe:
it works on a list of any length.
list.flatMap
def list.flatMap: [c] list(a), ([c] a -> list(b)) -> list(b)
The lists f gives for each element, joined end to end. Stack-safe: it works however long the
lists are.
list.filter
def list.filter: [c] list(a), ([c] a -> bool) -> list(a)
The elements keep holds for, in order. Stack-safe: it works on a list of any length.
list.filterMap
def list.filterMap: [c] list(a), ([c] a -> #some(b) | #skip) -> list(b)
The values f gives as #some, in order, leaving out the elements it gives #skip for: a map
and a filter in one walk. Stack-safe: it works on a list of any length.
list.partition
def list.partition: [c] list(a), ([c] a -> bool) -> (list(a), list(a))
The elements test holds for and the elements it fails for, each in order. Stack-safe: it works on
a list of any length.
list.find
def list.find: [c] list(a), ([c] a -> bool) -> #some(a) | #notFound
The first element matches holds for, or #notFound.
list.select
def list.select: [c, d] list(a), ([c] a -> [d] seq(b)) -> list(b)
The values f yields for each element in turn, in the order it yields them. A lambda with
yield in it is a sequence (see Yield), so items \list.select { item -> if item is #other(v) then yield v } gives the payload of each #other.
list.selectOne
def list.selectOne: [c, d] list(a), ([c] a -> [d] seq(b)) -> #some(b) | #notFound
The first value f yields, running it on the elements in turn as list.select does, or #notFound
when it yields none. It stops at the first yield: f runs on no element after the one it yields
for, and the code after that yield doesn’t run.
list.all
def list.all: [c] list(a), ([c] a -> bool) -> bool
Whether test holds for every element (so true for an empty list).
list.any
def list.any: [c] list(a), ([c] a -> bool) -> bool
Whether test holds for any element (so false for an empty list).
list.foldBack
def list.foldBack: [c] list(a), b, ([c] (b, a) -> b) -> b
list.fold from the last element to the first.
list.append
def list.append: list(a), a -> list(a)
xs with x added at the end.
list.flatten
def list.flatten: list(list(a)) -> list(a)
The lists of xss joined end to end. Stack-safe: it works however long the lists are.
list.take
def list.take: list(a), int -> list(a)
The first count elements (all of them when there are fewer). Stack-safe: it works on a list of
any length.
list.takeWhile
def list.takeWhile: [c] list(a), ([c] a -> bool) -> list(a)
The elements before the first one keep fails for. Stack-safe: it works on a list of any length.
list.dropLast
def list.dropLast: list(a) -> list(a)
All the elements but the last (no elements for an empty list). Stack-safe: it works on a list of any length.
list.skip
def list.skip: list(a), int -> list(a)
The elements after the first count.
list.skipWhile
def list.skipWhile: [c] list(a), ([c] a -> bool) -> list(a)
The elements from the first one test fails for, so list.takeWhile(xs, f) ++ list.skipWhile(xs, f)
is xs.
list.zip
def list.zip: list(a), list(b) -> list((a, b))
Pairs of the elements at the same position, as long as the shorter list. Stack-safe: it works on lists of any length.
list.zipWith
def list.zipWith: [c] list(a), list(b), ([c] (a, b) -> d) -> list(d)
f applied to the elements of xs and ys in pairs, stopping at the end of the shorter, as
list.zip does: [1, 2, 3] \zipWith([10, 20]) { + } is [11, 22]. Stack-safe: it works on
lists of any length.
list.intersperse
def list.intersperse: list(a), a -> list(a)
xs with separator between each pair of neighbouring elements: [1, 2, 3] \intersperse(0) is
[1, 0, 2, 0, 3]. Stack-safe: it works on a list of any length.
list.chunks
def list.chunks: list(a), int -> list(list(a))
xs cut into lists of size elements, in order; the last is shorter when size doesn’t divide
the length: [1, 2, 3, 4, 5] \chunks(2) is [[1, 2], [3, 4], [5]]. A size below 1 crashes.
Stack-safe: it works on a list of any length.
list.windows
def list.windows: list(a), int -> list(list(a))
Every run of size neighbouring elements, in order: [1, 2, 3, 4] \windows(2) is
[[1, 2], [2, 3], [3, 4]], and a list shorter than size has none. A size below 1 crashes.
Stack-safe: it works on a list of any length.
list.scan
def list.scan: [c] list(a), b, ([c] (b, a) -> b) -> list(b)
The running totals of a fold: initial, then each value list.fold passes along, so the last
is what the fold gives back: [1, 2, 3] \scan(0) { + } is [0, 1, 3, 6]. Stack-safe: it works on
a list of any length.
list.unzip
def list.unzip: list((a, b)) -> (list(a), list(b))
The first parts of the pairs and their second parts, each in order: the inverse of list.zip for
lists of equal length. Stack-safe: it works on a list of any length.
list.distinct
def list.distinct: [Eq(a)] list(a) -> list(a)
The elements without repeats, each kept where it first appears. Elements are compared with ==,
by their structure, so this works for lists of anything but functions.
list.distinctBy
def list.distinctBy: [Eq(b), Hash(b), c] list(a), ([c] a -> b) -> list(a)
The elements without two of the same key, each kept where the first with its key appears:
list.distinctBy(people, { p -> p.name }) keeps one person of each name. Stack-safe: it works on a
list of any length.
list.sortWith
def list.sortWith: [c] list(a), ([c] (a, a) -> #less | #equal | #greater) -> list(a)
The elements in the order order gives: order(a, b) says whether a comes before b
(#less), after it (#greater), or either way (#equal), as compare and int.compare do.
It sorts by an order that isn’t a type’s own: { a, b -> b.age \int.compare(a.age) } sorts by
age, oldest first, and one that compares a second key when the first is #equal sorts by both.
The sort is stable: elements order finds equal keep their order. Stack-safe: it works on a list
of any length.
list.sortBy
def list.sortBy: [Ord(b), c] list(a), ([c] a -> b) -> list(a)
The elements in ascending order of key. The sort is stable: elements with the same key keep
their order. A key can be of any type with an order: list.sortBy(people, { p -> p.name }).
Stack-safe: it works on a list of any length.
list.sortByDescending
def list.sortByDescending: [Ord(b), c] list(a), ([c] a -> b) -> list(a)
The elements in descending order of key: list.sortByDescending(people, { p -> p.age }) puts
the oldest first. The sort is stable: elements with the same key keep their order, which reversing
list.sortBy’s result would not do. Stack-safe: it works on a list of any length.
list.sort
def list.sort: [Ord(a)] list(a) -> list(a)
The elements in ascending order of their Ord: numbers numerically, strings by their bytes,
tuples and lists position by position. The sort is stable. Records and tags have no order, so a
list of them is sorted with list.sortBy and a key. Stack-safe: it works on a list of any length.
list.sortDescending
def list.sortDescending: [Ord(a)] list(a) -> list(a)
The elements in descending order of their Ord, greatest first: [3, 1, 2] gives [3, 2, 1].
The sort is stable. Stack-safe: it works on a list of any length.
list.min
def list.min: [Ord(a)] list(a) -> #some(a) | #emptyList
The least element, or #emptyList. Of several least elements, the first.
list.max
def list.max: [Ord(a)] list(a) -> #some(a) | #emptyList
The greatest element, or #emptyList. Of several greatest elements, the first. Elements are
ordered by their Ord, so a list of records has none: use list.maxBy with a key.
list.minBy
def list.minBy: [Ord(b), c] list(a), ([c] a -> b) -> #some(a) | #emptyList
The element with the least key, or #emptyList. Of several elements with the least key, the
first. key is called once for each element.
list.maxBy
def list.maxBy: [Ord(b), c] list(a), ([c] a -> b) -> #some(a) | #emptyList
The element with the greatest key, or #emptyList. Of several elements with the greatest key,
the first. key is called once for each element.
list.unfold
def list.unfold: [c] b, ([c] b -> #some(a, b) | #done) -> list(a)
The elements step gives, starting from state: #some(x, next) gives x and carries on from
next, and #done ends the list. Stack-safe: it works however many elements step gives.
list.init
def list.init: [c] int, ([c] int -> a) -> list(a)
The list of count elements whose element at each position is f applied to the position:
list.init(3, { i -> i * 2 }) is [0, 2, 4]. f is called on the positions in order, and a
count of zero or less gives []. Stack-safe: it works for any count.
list.replicate
def list.replicate: (a, count: int) -> list(a)
count copies of x: list.replicate(0, count = 3) is [0, 0, 0]. A count of zero or less
gives []. Stack-safe: it works for any count.