# List

`case Nil`

`case Cons(t, List[t])`

The List type.

A list is either the empty list represented by `Nil`

, or
an element `v`

followed by a list `vs`

represented by `v :: vs`

.

## Definitions

`def ap(f: List[a -> b \ ef], x: List[a]): List[b] \ ef`

SourceApply every function from `f`

to every argument from `x`

and return a list with all results.
For `f = f1, f2, ...`

and `x = x1, x2, ...`

the results appear in the order
`f1(x1), f1(x2), ..., f2(x1), f2(x2), ...`

.

`def append(l1: List[a], l2: List[a]): List[a]`

SourceReturns `l2`

appended to `l1`

.

The infix operator `:::`

is an alias for `append`

(`l1 ::: l2 = append(l1, l2)`

).

`def count(f: a -> Bool \ ef, l: List[a]): Int32 \ ef`

SourceReturns the number of elements in `l`

that satisfy the predicate `f`

.

Returns the list `l`

with duplicates removed. The first occurence of
an element is kept and except for the removal of subsequent duplicates
the order of `l`

is preserved.

`distinct`

uses the Flix's builtin equality test. Use `distinctWith`

if you
need a custom equality test.

`def distinctWith(f: a -> (a -> Bool), l: List[a]): List[a]`

SourceReturns the list `l`

with duplicates removed using the supplied function
`f`

for comparison. The first occurrence of an element is kept and except
for the removal of subsequent duplicates the order of `l`

is preserved.

`def drop(n: Int32, l: List[a]): List[a]`

SourceReturns `l`

without the first `n`

elements.

Returns `Nil`

if `n > length(l)`

.
Returns `l`

if `n < 0`

.

`def dropWhile(f: a -> Bool \ ef, l: List[a]): List[a] \ ef`

SourceReturns `l`

without the longest prefix that satisfies the predicate `f`

.

`def enumerator(rc: Region[r], l: List[a]): Iterator[(Int32, a), r, r] \ r`

SourceReturns an iterator over `l`

zipped with the indices of the elements.

`def exists(f: a -> Bool \ ef, l: List[a]): Bool \ ef`

SourceReturns `true`

if and only if at least one element in `l`

satisfies the predicate `f`

.

Returns `false`

if `l`

is empty.

`def filter(f: a -> Bool \ ef, l: List[a]): List[a] \ ef`

SourceReturns a list of every element in `l`

that satisfies the predicate `f`

.

`def filterMap(f: a -> Option[b] \ ef, l: List[a]): List[b] \ ef`

SourceCollects the results of applying the partial function `f`

to every element in `l`

.

`def find(f: a -> Bool \ ef, l: List[a]): Option[a] \ ef`

SourceAlias for `findLeft`

.

`def findLeft(f: a -> Bool \ ef, l: List[a]): Option[a] \ ef`

SourceOptionally returns the first element of `l`

that satisfies the predicate `f`

when searching from left to right.

`def findMap(f: a -> Option[b] \ ef, l: List[a]): Option[b] \ ef`

SourceReturns the first non-None result of applying the partial function `f`

to each element of `l`

.

Returns `None`

if every element of `l`

is `None`

.

`def findRight(f: a -> Bool \ ef, l: List[a]): Option[a] \ ef`

SourceOptionally returns the first element of `l`

that satisfies the predicate `f`

when searching from right to left.

`def flatMap(f: a -> List[b] \ ef, l: List[a]): List[b] \ ef`

SourceReturns the result of applying `f`

to every element in `l`

and concatenating the results.

`def flatten(l: List[List[a]]): List[a]`

SourceReturns the concatenation of the elements in `l`

.

Returns the result of applying `combine`

to all the elements in `l`

, using `empty`

as the initial value.

`def fold2(f: c -> (a -> (b -> c \ ef)), c: c, l1: List[a], l2: List[b]): c \ ef`

SourceAlias for `foldLeft2`

.

`def foldLeft(f: b -> (a -> b \ ef), s: b, l: List[a]): b \ ef`

SourceApplies `f`

to a start value `s`

and all elements in `l`

going from left to right.

That is, the result is of the form: `f(...f(f(s, x1), x2)..., xn)`

.

`def foldLeft2(f: c -> (a -> (b -> c \ ef)), c: c, l1: List[a], l2: List[b]): c \ ef`

SourceAccumulates the result of applying `f`

pairwise to the elements of `l1`

and `l2`

starting with the initial value `c`

and going from left to right.

Returns the result of mapping each element and combining the results.

`def foldRight(f: a -> (b -> b \ ef), s: b, l: List[a]): b \ ef`

SourceApplies `f`

to a start value `s`

and all elements in `l`

going from right to left.

That is, the result is of the form: `f(x1, ...f(xn-1, f(xn, s))...)`

.

`def foldRight2(f: a -> (b -> (c -> c \ ef)), c: c, l1: List[a], l2: List[b]): c \ ef`

SourceAccumulates the result of applying `f`

pairwise to the elements of `l1`

and `l2`

starting with the initial value `c`

and going from right to left.

`def foldRightWithCont(f: a -> ((Unit -> b \ ef) -> b \ ef), z: b, l: List[a]): b \ ef`

SourceApplies `f`

to a start value `z`

and all elements in `l`

going from right to left.

That is, the result is of the form: `f(x1, ...f(xn-1, f(xn, z))...)`

.
A `foldRightWithCont`

allows early termination by not calling the continuation.

`def forAll(f: a -> Bool \ ef, l: List[a]): Bool \ ef`

SourceReturns `true`

if and only if all elements in `l`

satisfy the predicate `f`

.

Returns `true`

if `l`

is empty.

`def forEach(f: a -> Unit \ ef, l: List[a]): Unit \ ef`

SourceApplies `f`

to every element of `l`

.

`def forEachWithIndex(f: Int32 -> (a -> Unit \ ef), l: List[a]): Unit \ ef`

SourceApplies `f`

to every element of `l`

along with that element's index.

Returns the frequency for each element in list `l`

`def groupBy(f: a -> (a -> Bool), l: List[a]): List[List[a]]`

SourcePartitions `l`

into sublists such that for any two elements `x`

and `y`

in a sublist, `f(x, y)`

is true.

A sublist is created by iterating through the remaining elements of `l`

from left to right and adding an
element to the sublist if and only if doing so creates no conflicts with the elements already in the sublist.

The function `f`

must be pure.

`def head(l: List[a]): Option[a]`

SourceReturns `Some(x)`

if `x`

is the first element of `l`

.

Returns `None`

if `l`

is empty.

Optionally returns the position of `x`

in `l`

.

`def init(l: List[a]): Option[List[a]]`

SourceReturns the sublist of `l`

without the last element.
Returns `None`

if the list `l`

is `Nil`

.

`def intercalate(l1: List[a], l2: List[List[a]]): List[a]`

SourceReturns the concatenation of the elements in `l2`

with the elements of `l1`

inserted between every two adjacent elements.

That is, returns `y1 :: x1 ... xn :: y2 :: ... yn-1 :: x1 :: ... :: xn :: yn :: Nil`

.

`def intersperse(a: a, l: List[a]): List[a]`

SourceReturns `l`

with `x`

inserted between every two adjacent elements.

`def isEmpty(l: List[a]): Bool`

SourceReturns true if and only if `l`

is the empty list, i.e. `Nil`

.

Returns `true`

if and only if `l1`

is an infix of `l2`

.

Returns `true`

if and only if `l1`

is a prefix of `l2`

.

Returns `true`

if and only if `l1`

is a suffix of `l2`

.

`def iterator(rc: Region[r], xs: List[a]): Iterator[a, r, r] \ r`

SourceReturns an iterator over `l`

.

Returns the concatenation of the string representation
of each element in `l`

with `sep`

inserted between each element.

`def joinWith(f: a -> String \ ef, sep: String, l: List[a]): String \ ef`

SourceReturns the concatenation of the string representation
of each element in `l`

according to `f`

with `sep`

inserted between each element.

`def last(l: List[a]): Option[a]`

SourceReturns `Some(x)`

if `x`

is the last element of `l`

.

Returns `None`

if `l`

is empty.

`def length(l: List[a]): Int32`

SourceReturns the length of `l`

.

`def map(f: a -> b \ ef, l: List[a]): List[b] \ ef`

SourceReturns the result of applying `f`

to every element in `l`

.

That is, the result is of the form: `f(x1) :: f(x2) :: ...`

.

`def map2(f: t1 -> (t2 -> r \ ef), l1: List[t1], l2: List[t2]): List[r] \ ef`

SourceLift a binary function to work on lists of its original arguments, returning a list
of applying all combinations of arguments.
For argument lists `l1 = x1, x2, ...`

and `l2 = y1, y2, ...`

the results appear in the order
`f(x1,y1), f(x1,y2), ..., f(x2,y1), f(x2,y2), ...`

.

`def map3(f: t1 -> (t2 -> (t3 -> r \ ef)), l1: List[t1], l2: List[t2], l3: List[t3]): List[r] \ ef`

SourceLift a ternary function to work on lists of its original arguments, returning a list
of applying all combinations of arguments.
For argument lists `l1 = x1, x2, ...`

, `l2 = y1, y2, ...`

and `l3 = z1, z2, ...`

the results appear
in the following order:

```
`
f(x1,y1,z1), f(x1,y1,z2), ..., f(x1,y2,z1), f(x1,y2,z2), ...,
f(x2,y1,z1), f(x2,y1,z2), ..., f(x2,y2,z1), f(x2,y2,z2), ...`
...
```

`

`def map4(f: t1 -> (t2 -> (t3 -> (t4 -> r \ ef))), l1: List[t1], l2: List[t2], l3: List[t3], l4: List[t4]): List[r] \ ef`

SourceLift a 4-ary function to work on lists of its original arguments, returning a list
of applying all combinations of arguments. The results appear in the order extending the pattern from `map3`

.

`def map5(f: t1 -> (t2 -> (t3 -> (t4 -> (t5 -> r \ ef)))), l1: List[t1], l2: List[t2], l3: List[t3], l4: List[t4], l5: List[t5]): List[r] \ ef`

SourceLift a 5-ary function to work on lists of its original arguments, returning a list
of applying all combinations of arguments. The results appear in the order extending the pattern from `map3`

.

`def mapWithIndex(f: Int32 -> (a -> b \ ef), l: List[a]): List[b] \ ef`

SourceReturns the result of applying `f`

to every element in `l`

along with that element's index.

That is, the result is of the form: `f(x1, 0) :: f(x2, 1) :: ...`

.

Optionally finds the largest element of `l`

according to the `Order`

on `a`

.

Returns `None`

if `l`

is empty.

`def maximumBy(cmp: a -> (a -> Comparison), l: List[a]): Option[a]`

SourceOptionally finds the largest element of `l`

according to the given comparator `cmp`

.

Returns `None`

if `l`

is empty.

Returns `true`

if and only if `l`

contains the element `x`

.

Merges the two lists `l1`

and `l2`

. Assuming they are both sorted.
If two elements compare `EqualTo`

, then the element of `l1`

is first in the result.

Optionally finds the smallest element of `l`

according to the `Order`

on `a`

.

Returns `None`

if `l`

is empty.

`def minimumBy(cmp: a -> (a -> Comparison), l: List[a]): Option[a]`

SourceOptionally finds the smallest element of `l`

according to the given comparator `cmp`

.

Returns `None`

if `l`

is empty.

`def partition(f: a -> Bool \ ef, l: List[a]): (List[a], List[a]) \ ef`

SourceReturns a pair of lists `(l1, l2)`

.

`l1`

contains all elements of `l`

that satisfy the predicate `f`

.
`l2`

contains all elements of `l`

that do not satisfy the predicate `f`

.

`def patch(i: Int32, n: Int32, l1: List[a], l2: List[a]): List[a]`

SourceReturns `l2`

with the `n`

elements starting at index `i`

replaced with the elements of `l1`

.

If any of the indices `i, i+1, i+2, ... , i+n-1`

are out of range in `l2`

then no patching is done at these indices.
If `l1`

becomes depleted then no further patching is done.
If patching occurs at index `i+j`

in `l2`

, then the element at index `j`

in `l1`

is used.

`def permutations(l: List[a]): List[List[a]]`

SourceReturns all permutations of `l`

in lexicographical order by element indices in `l`

.

That is, `l`

is the first permutation and `reverse(l)`

is the last permutation.

`def point(a: a): List[a]`

SourceReturn the singleton list with element `x`

.

`def range(b: Int32, e: Int32): List[Int32]`

SourceReturns a list of all integers between `b`

(inclusive) and `e`

(exclusive).

Returns `Nil`

if `b >= e`

.

`def reduceLeft(f: a -> (a -> a \ ef), l: List[a]): Option[a] \ ef`

SourceApplies `f`

to all elements in `l`

going from left to right until a single value `v`

is obtained. Returns `Some(v)`

.

That is, the result is of the form: `Some(f(...f(f(x1, x2), x3)..., xn))`

Returns `None`

if `l`

is empty.

`def reduceRight(f: a -> (a -> a \ ef), l: List[a]): Option[a] \ ef`

SourceApplies `f`

to all elements in `l`

going from right to left until a single value `v`

is obtained. Returns `Some(v)`

.

That is, the result is of the form: `Some(f(x1, ...f(xn-2, f(xn-1, xn))...))`

Returns `None`

if `l`

is empty.

`def repeat(n: Int32, a: a): List[a]`

SourceReturns a list with the element `x`

repeated `n`

times.

Returns `Nil`

if `n < 0`

.

Returns `l`

with every occurrence of `from`

replaced by `to`

.

`def reverse(l: List[a]): List[a]`

SourceReturns the reverse of `l`

.

`def rotateLeft(n: Int32, l: List[a]): List[a]`

SourceReturns `l`

with its elements rotated `n`

positions to the left.

That is, returns a new list where the first `n mod length(l)`

elements in `l`

are the last `n mod length(l)`

elements of the new list.

`def rotateRight(n: Int32, l: List[a]): List[a]`

SourceReturns `l`

with its elements rotated `n`

positions to the right.

That is, returns a new list where the last `n mod length(l)`

elements in `l`

are the first `n mod length(l)`

elements of the new list.

`def scan(f: b -> (a -> b \ ef), s: b, l: List[a]): List[b] \ ef`

SourceAlias for `scanLeft`

.

`def scanLeft(f: b -> (a -> b \ ef), s: b, l: List[a]): List[b] \ ef`

SourceAccumulates the result of applying `f`

to `l`

going left to right.

That is, the result is of the form: `s :: f(s, x1) :: f(f(s, x1), x2) ...`

.

`def scanRight(f: a -> (b -> b \ ef), s: b, l: List[a]): List[b] \ ef`

SourceAccumulates the result of applying `f`

to `l`

going right to left.

That is, the result is of the form: `... f(xn-1, f(xn, s)) :: f(xn, s) :: s`

.

`def sequence(l: List[m[a]]): m[List[a]] with Applicative[m]`

SourceReturns the result of running all the actions in the list `l`

going from left
to right.

`def shuffle(rnd: Random, l: List[a]): List[a] \ IO`

SourceShuffles `l`

using the Fisherâ€“Yates shuffle.

`def slice(start: { start = Int32 }, end: { end = Int32 }, l: List[a]): List[a]`

SourceReturns the sublist of `l`

from index `start`

(inclusive) to index `end`

(exclusive).

That is, an element at index `i`

in `l`

is part of the returned sublist if and only if `i >= start`

and `i < end`

.
Note: Indices that are out of bounds in `l`

are not considered (i.e. slice(start, end, l) = slice(max(0, start), min(length(l), end), l)).

Sort list `l`

so that elements are ordered from low to high according to their `Order`

instance.

The sort is not stable, i.e., equal elements may appear in a different order than in the input `l`

.

The sort implementation is a Quicksort.

Sort list `l`

so that elements are ordered from low to high according to the `Order`

instance
for the values obtained by applying `f`

to each element.

The sort is not stable, i.e., equal elements may appear in a different order than in the input `l`

.

The sort implementation is a Quicksort.

`def sortWith(cmp: a -> (a -> Comparison), l: List[a]): List[a]`

SourceSort list `l`

so that elements are ordered from low to high according to the comparison function `cmp`

.

The sort is not stable, i.e., equal elements may appear in a different order than in the input `l`

.

The sort implementation is a Quicksort.

`def span(f: a -> Bool, l: List[a]): (List[a], List[a])`

SourceReturns a pair of lists `(l1, l2)`

.

`l1`

is the longest prefix of `l`

that satisfies the predicate `f`

.
`l2`

is the remainder of `l`

.

The function `f`

must be pure.

`def splitAt(n: Int32, xs: List[a]): (List[a], List[a])`

SourceSplit the list `xs`

at the position `n`

returning the left and right parts.
Position `n`

is included in the right part.

Example: `splitAt(2, 1::2::3::4::Nil)`

returns `(1::2::Nil, 3::4::Nil)`

Returns `(xs, Nil)`

if `n > length(xs)`

.
Returns `(Nil, xs)`

if `n < 0`

.

`def subsequences(l: List[a]): List[List[a]]`

SourceReturns all subsequences of `l`

in lexicographical order by element indices in `l`

.

That is, `l`

is the first subsequence and `Nil`

is the last subsequence.

`def sum(l: List[Int32]): Int32`

SourceReturns the sum of all elements in the list `l`

.

`def sumWith(f: a -> Int32 \ ef, l: List[a]): Int32 \ ef`

SourceReturns the sum of all elements in the list `l`

according to the function `f`

.

`def take(n: Int32, l: List[a]): List[a]`

SourceReturns the first `n`

elements of `l`

.

Returns `l`

if `n > length(l)`

.
Returns `Nil`

if `n < 0`

.

`def takeWhile(f: a -> Bool \ ef, l: List[a]): List[a] \ ef`

SourceReturns the longest prefix of `l`

that satisfies the predicate `f`

.

`def toArray(rc: Region[r], l: List[a]): Array[a, r] \ r`

SourceReturns the list `l`

as an array.

`def toChain(l: List[a]): Chain[a]`

SourceReturns the list `l`

as a chain.

Returns the association list `l`

as a `DelayMap`

.

If `l`

contains multiple mappings with the same key, `toDelayMap`

does not
make any guarantees about which mapping will be in the resulting map.

Returns the association list `l`

as a map.

If `l`

contains multiple mappings with the same key, `toMap`

does not
make any guarantees about which mapping will be in the resulting map.

Returns a map with elements of `s`

as keys and `f`

applied as values.

If `s`

contains multiple mappings with the same key, `toMapWith`

does not
make any guarantees about which mapping will be in the resulting map.

`def toMutDeque(rc: Region[r], l: List[a]): MutDeque[a, r] \ r`

SourceReturns `l`

as a MutDeque.

`def toMutList(rc: Region[r], l: List[a]): MutList[a, r] \ r`

SourceReturns `l`

as a mutable list.

`def toNec(l: List[a]): Option[Nec[a]]`

SourceReturns the list `l`

as `Option[Nec[a]]`

.

If `l`

is empty return `None`

, otherwise return the Nec wrapped in `Some`

.

`def toNel(l: List[a]): Option[Nel[a]]`

SourceReturns the list `l`

as `Option[Nel[a]]`

.

If `l`

is empty return `None`

, otherwise return the Nel wrapped in `Some`

.

`def toVector(l: List[a]): Vector[a]`

SourceReturns the list `l`

as a vector.

`def transpose(l: List[List[a]]): List[List[a]]`

SourceReturns the transpose of `l`

.

Returns `l`

if the dimensions of the elements of `l`

are mismatched.

`def traverse(f: a -> m[b] \ ef, l: List[a]): m[List[b]] \ ef with Applicative[m]`

SourceReturns the result of applying the applicative mapping function `f`

to all the elements of the
list `l`

going from left to right.

`def unfold(f: s -> Option[(a, s)] \ ef, st: s): List[a] \ ef`

SourceBuild a list by applying `f`

to the seed value `st`

.

`f`

should return `Some(a,st1)`

to signal a new list element `a`

and a new seed value `st1`

.

`f`

should return `None`

to signal the end of building the list.

`def unfoldWithIter(next: Unit -> Option[a] \ ef): List[a] \ ef`

SourceBuild a list by applying the function `next`

to `()`

. `next`

is expected to encapsulate
a stateful resource such as a file handle that can be iterated.

`next`

should return `Some(a)`

to signal a new list element `a`

.

`next`

should return `None`

to signal the end of building the list.

`def unfoldWithOkIter(next: Unit -> Result[e, Option[a]] \ ef): Result[e, List[a]] \ ef`

SourceBuild a list by applying the function `next`

to `()`

. `next`

is expected to encapsulate
a stateful resource such as a file handle that can be iterated.

`next`

should return `Ok(Some(a)`

to signal a new list element `Ok(a)`

.

`next`

should return `Ok(None)`

to signal the end of building the list.

`next`

should return `Err(e)`

to signal that an error occurred. The function returns `Err(e)`

.

`def unzip(l: List[(a, b)]): (List[a], List[b])`

SourceReturns a pair of lists, the first containing all first components in `l`

and the second containing all second components in `l`

.

`def unzip3(l: List[(a, b, c)]): (List[a], List[b], List[c])`

SourceReturns a triple of lists, the first containing all first components in `l`

the second containing all second components in `l`

and the third containing all
third components in `l`

.

`def update(i: Int32, a: a, l: List[a]): List[a]`

SourceReturns `l`

with the element at index `i`

replaced by `x`

.

Returns `l`

if `i < 0`

or `i > length(l)-1`

.

`def zip(l1: List[a], l2: List[b]): List[(a, b)]`

SourceReturns a list where the element at index `i`

is `(a, b)`

where
`a`

is the element at index `i`

in `l1`

and `b`

is the element at index `i`

in `l2`

.

If either `l1`

or `l2`

becomes depleted, then no further elements are added to the resulting list.

`def zip3(l1: List[a], l2: List[b], l3: List[c]): List[(a, b, c)]`

SourceReturns a list where the element at index `i`

is `(a, b, c)`

where
`a`

is the element at index `i`

in `l1`

, `b`

is the element at index `i`

in `l2`

and `c`

is the element at index `i`

in `l3`

.

If any one of `l1`

, `l2`

or `l3`

become depleted, then no further elements are added to the resulting list.

`def zipWith(f: a -> (b -> c \ ef), l1: List[a], l2: List[b]): List[c] \ ef`

SourceReturns a list where the element at index `i`

is `f(a, b)`

where
`a`

is the element at index `i`

in `l1`

and `b`

is the element at index `i`

in `l2`

.

If either `l1`

or `l2`

becomes depleted, then no further elements are added to the resulting list.

`def zipWith3(f: a -> (b -> (c -> d \ ef)), l1: List[a], l2: List[b], l3: List[c]): List[d] \ ef`

SourceReturns a list where the element at index `i`

is `f(a, b, c)`

where
`a`

is the element at index `i`

in `l1`

, `b`

is the element at index `i`

in `l2`

and `c`

is the element at index `i`

in `l3`

.

If any one of `l1`

, `l2`

or `l3`

become depleted, then no further elements are added to the resulting list.

`def zipWithA(f: a -> (b -> f[c] \ ef), xs: List[a], ys: List[b]): f[List[c]] \ ef with Applicative[f]`

SourceGeneralize `zipWith`

to an applicative functor `f`

.

`def zipWithIndex(l: List[a]): List[(Int32, a)]`

SourceReturns a list where each element `e`

is mapped to `(i, e)`

where `i`

is the index of `e`

.