API / Core / List

List

t

RESCRIPT
type t<'a> = list<'a>

Collection functions for manipulating the list data structures, a singly-linked list.

Prefer Array if you need any of the following:

  • Random access of element

  • Better interop with JavaScript

  • Better memory usage & performance.

length

RESCRIPT
let length: t<'a> => int

length(list) returns the length of list.

Examples

RESCRIPT
List.length(list{1, 2, 3}) // 3

size

RESCRIPT
let size: t<'a> => int

size(list). See length

Examples

RESCRIPT
List.size(list{1, 2, 3}) // 3

head

RESCRIPT
let head: t<'a> => option<'a>

head(list) returns Some(value) where value is the first element in the list, or None if list is an empty list.

Examples

RESCRIPT
List.head(list{}) // None
List.head(list{1, 2, 3}) // Some(1)

headExn

RESCRIPT
let headExn: t<'a> => 'a

headExn(list) same as head.

Examples

RESCRIPT
List.headExn(list{1, 2, 3}) // 1

List.headExn(list{}) // Raises an Error

Exceptions

  • Raises an Error if list is empty.

tail

RESCRIPT
let tail: t<'a> => option<t<'a>>

tail(list) returns None if list is empty, otherwise it returns Some(tail) where tail is everything except the first element of list.

Examples

RESCRIPT
List.tail(list{1, 2, 3}) // Some(list{2, 3})

List.tail(list{}) // None

tailExn

RESCRIPT
let tailExn: t<'a> => t<'a>

tailExn(list) same as tail.

Examples

RESCRIPT
List.tailExn(list{1, 2, 3}) // list{2, 3}

List.tailExn(list{}) // Raises an Error

Exceptions

  • Raises an Error if list is empty.

add

RESCRIPT
let add: (t<'a>, 'a) => t<'a>

add(list, value) adds a value to the beginning of list list.

Examples

RESCRIPT
List.add(list{2, 3}, 1) // list{1, 2, 3}

List.add(list{"World", "!"}, "Hello") // list{"Hello", "World", "!"}

get

RESCRIPT
let get: (t<'a>, int) => option<'a>

get(list, index) return the index element in list, or None if index is larger than the length of list list.

Examples

RESCRIPT
let abc = list{"A", "B", "C"}

abc->List.get(1) // Some("B")

abc->List.get(4) // None

getExn

RESCRIPT
let getExn: (t<'a>, int) => 'a

getExn(list, index) same as get.

Examples

RESCRIPT
let abc = list{"A", "B", "C"}

abc->List.getExn(1) // "B"

abc->List.getExn(4) // Raises an Error

Exceptions

  • Raises an Error if index is larger than the length of list.

make

RESCRIPT
let make: (int, 'a) => t<'a>

make(length, value) returns a list of length length with each element filled with value. Returns an empty list if value is negative.

Examples

RESCRIPT
List.make(3, 1) // list{1, 1, 1}

makeBy

RESCRIPT
let makeBy: (int, int => 'a) => t<'a>

makeBy(length, f) return a list of length length with element initialized with f. Returns an empty list if length is negative.

Examples

RESCRIPT
List.makeBy(5, i => i) // list{0, 1, 2, 3, 4}

List.makeBy(5, i => i * i) // list{0, 1, 4, 9, 16}

toShuffled

RESCRIPT
let toShuffled: t<'a> => t<'a>

toShuffled(list) returns a new list in random order.

Examples

RESCRIPT
List.toShuffled(list{1, 2, 3}) // list{2, 1, 3}

drop

RESCRIPT
let drop: (t<'a>, int) => option<t<'a>>

drop(list, value) return a new list, dropping the first value element. Returns None if list has fewer than value elements.

Examples

RESCRIPT
list{1, 2, 3}->List.drop(2) // Some(list{3})

list{1, 2, 3}->List.drop(3) // Some(list{})

list{1, 2, 3}->List.drop(4) // None

take

RESCRIPT
let take: (t<'a>, int) => option<t<'a>>

take(list, value) returns a list with the first value elements from list, or None if list has fewer than value elements.

Examples

RESCRIPT
list{1, 2, 3}->List.take(1) // Some(list{1})

list{1, 2, 3}->List.take(2) // Some(list{1, 2})

list{1, 2, 3}->List.take(4) // None

splitAt

RESCRIPT
let splitAt: (t<'a>, int) => option<(list<'a>, list<'a>)>

splitAt(list, n) split the list list at n. Returns None when the length of list is less than n.

Examples

RESCRIPT
list{"Hello", "World"}->List.splitAt(1) // Some((list{"Hello"}, list{"World"}))

list{0, 1, 2, 3, 4}->List.splitAt(2) // Some((list{0, 1}, list{2, 3, 4}))

concat

RESCRIPT
let concat: (t<'a>, t<'a>) => t<'a>

concat(list1, list2) returns the list obtained by adding list1 after list2.

Examples

RESCRIPT
List.concat(list{1, 2, 3}, list{4, 5}) // list{1, 2, 3, 4, 5}

concatMany

RESCRIPT
let concatMany: array<t<'a>> => t<'a>

concatMany(arr) returns the list obtained by concatenating all the lists in array arr, in order.

Examples

RESCRIPT
List.concatMany([list{1, 2, 3}, list{}, list{3}]) // list{1, 2, 3, 3}

reverseConcat

RESCRIPT
let reverseConcat: (t<'a>, t<'a>) => t<'a>

reverseConcat(list1, list2) is equivalent to writing: concat(reverse(list1, list2)

Examples

RESCRIPT
List.reverseConcat(list{1, 2}, list{3, 4}) // list{2, 1, 3, 4}

flatten

RESCRIPT
let flatten: t<t<'a>> => t<'a>

flatten(list) return the list obtained by concatenating all the lists in list, in order.

Examples

RESCRIPT
List.flatten(list{list{1, 2, 3}, list{}, list{3}}) // list{1, 2, 3, 3}

map

RESCRIPT
let map: (t<'a>, 'a => 'b) => t<'b>

map(list, f) returns a new list with f applied to each element of list.

Examples

RESCRIPT
list{1, 2}->List.map(x => x + 1) // list{3, 4}

zip

RESCRIPT
let zip: (t<'a>, t<'b>) => t<('a, 'b)>

zip(list1, list2) returns a list of pairs from the two lists with the length of the shorter list.

Examples

RESCRIPT
List.zip(list{1, 2}, list{3, 4, 5}) // list{(1, 3), (2, 4)}

zipBy

RESCRIPT
let zipBy: (t<'a>, t<'b>, ('a, 'b) => 'c) => t<'c>

zipBy(list1, list2, f). See zip

Examples

RESCRIPT
List.zipBy(list{1, 2, 3}, list{4, 5}, (a, b) => 2 * a + b) // list{6, 9}

mapWithIndex

RESCRIPT
let mapWithIndex: (t<'a>, (int, 'a) => 'b) => t<'b>

mapWithIndex(list, f) applies f to each element of list. Function f takes two arguments: the index starting from 0 and the element from list, in that order.

Examples

RESCRIPT
list{1, 2, 3}->List.mapWithIndex((index, x) => index + x) // list{1, 3, 5}

fromArray

RESCRIPT
let fromArray: array<'a> => t<'a>

fromArray(arr) converts the given array arr to a list.

Examples

RESCRIPT
List.fromArray([1, 2, 3]) // list{1, 2, 3}

toArray

RESCRIPT
let toArray: t<'a> => array<'a>

toArray(list) converts the given list list to an array.

Examples

RESCRIPT
List.toArray(list{1, 2, 3}) // [1, 2, 3]

reverse

RESCRIPT
let reverse: t<'a> => t<'a>

reverse(list) returns a new list whose elements are those of list in reversed order.

Examples

RESCRIPT
List.reverse(list{1, 2, 3}) // list{3, 2, 1}

mapReverse

RESCRIPT
let mapReverse: (t<'a>, 'a => 'b) => t<'b>

mapReverse(list, f) is equivalent to map function.

Examples

RESCRIPT
let f = x => x * x
let l = list{3, 4, 5}

let withMap = List.map(l, f)->List.reverse
let withMapReverse = l->List.mapReverse(f)

Console.log(withMap == withMapReverse) // true

forEach

RESCRIPT
let forEach: (t<'a>, 'a => 'b) => unit

forEach(list, f) call f on each element of list from the beginning to end. f returns unit, so no new array is created. Use forEach when you are primarily concerned with repetitively creating side effects.

Examples

RESCRIPT
List.forEach(list{"a", "b", "c"}, x => Console.log("Item: " ++ x))
/*
  prints:
  Item: a
  Item: b
  Item: c
*/

forEachWithIndex

RESCRIPT
let forEachWithIndex: (t<'a>, (int, 'a) => 'b) => unit

forEachWithIndex(list, f, index) call f on each element of list from beginning to end. Function f takes two arguments: the index starting from 0 and the element from list. f returns unit.

Examples

RESCRIPT
List.forEachWithIndex(list{"a", "b", "c"}, (index, x) => {
  Console.log("Item " ++ Int.toString(index) ++ " is " ++ x)
})
/*
  prints:
  Item 0 is a
  Item 1 is b
  Item 2 is cc
*/

reduce

RESCRIPT
let reduce: (t<'a>, 'b, ('b, 'a) => 'b) => 'b

reduce(list, initialValue, f) applies f to each element of list from beginning to end. Function f has two parameters: the item from the list and an "accumulator", which starts with a value of initialValue. reduce returns the final value of the accumulator.

Examples

RESCRIPT
list{1, 2, 3, 4}->List.reduce(0, (a, b) => a + b) // 10

// same as

list{1, 2, 3, 4}->List.reduce(0, (acc, item) => acc + item) // 10

reduceWithIndex

RESCRIPT
let reduceWithIndex: (t<'a>, 'b, ('b, 'a, int) => 'b) => 'b

reduceWithIndex(list, initialValue, f) applies f to each element of list from beginning to end. Function f has three parameters: the item from the list and an "accumulator", which starts with a value of initialValue and the index of each element. reduceWithIndex returns the final value of the accumulator.

Examples

RESCRIPT
list{1, 2, 3, 4}->List.reduceWithIndex(0, (acc, item, index) => acc + item + index) // 16

reduceReverse

RESCRIPT
let reduceReverse: (t<'a>, 'b, ('b, 'a) => 'b) => 'b

reduceReverse(list, initialValue, f) works like reduce, except that function f is applied to each item of list from the last back to the first.

Examples

RESCRIPT
list{1, 2, 3, 4}->List.reduceReverse(0, (a, b) => a + b) // 10

list{1, 2, 3, 4}->List.reduceReverse(10, (a, b) => a - b) // 0

list{1, 2, 3, 4}->List.reduceReverse(list{}, List.add) // list{1, 2, 3, 4}

mapReverse2

RESCRIPT
let mapReverse2: (t<'a>, t<'b>, ('a, 'b) => 'c) => t<'c>

mapReverse2(list1, list2, f) is equivalent to List.zipBy(list1, list2, f)->List.reverse.

Examples

RESCRIPT
List.mapReverse2(list{1, 2, 3}, list{1, 2}, (a, b) => a + b) // list{4, 2}

forEach2

RESCRIPT
let forEach2: (t<'a>, t<'b>, ('a, 'b) => 'c) => unit

forEach2(list1, list2, f) is similar to forEach, but accepts two lists and stops at the length of the shorter list.

Examples

RESCRIPT
List.forEach2(list{"Z", "Y"}, list{"A", "B", "C"}, (x, y) => Console.log2(x, y))

/*
  prints:
  "Z" "A"
  "Y" "B"
*/

reduce2

RESCRIPT
let reduce2: (t<'b>, t<'c>, 'a, ('a, 'b, 'c) => 'a) => 'a

reduce2(list1, list2, initialValue, f) applies f to each element of list1 and list2 from beginning to end. Stops with the shorter list. Function f has three parameters: an accumulator which starts with a value of initialValue, an item from l1, and an item from l2. reduce2 returns the final value of the accumulator.

Examples

RESCRIPT
List.reduce2(list{1, 2, 3}, list{4, 5}, 0, (acc, x, y) => acc + x * x + y) // 0 + (1 * 1 + 4) + (2 * 2 + 5)

reduceReverse2

RESCRIPT
let reduceReverse2: (t<'a>, t<'b>, 'c, ('c, 'a, 'b) => 'c) => 'c

reduceReverse2(list1, list2, initialValue, f) applies f to each element of list1 and list2from end to beginning. Stops with the shorter list. Function f has three parameters: an accumulator which starts with a value of initialValue, an item from l1, and an item from l2. reduce2 returns the final value of the accumulator.

Examples

RESCRIPT
List.reduceReverse2(list{1, 2, 3}, list{4, 5}, 0, (acc, x, y) => acc + x * x + y) //  + (1 * 1 + 4) + (2 * 2 + 5)

every

RESCRIPT
let every: (t<'a>, 'a => bool) => bool

every(list, f) returns true if all elements in list satisfy f, where f is a predicate: a function taking an element and returning a bool.

Examples

RESCRIPT
let isBelow10 = value => value < 10

list{1, 9, 8, 2}->List.every(isBelow10) // true

list{1, 99, 8, 2}->List.every(isBelow10) // false

some

RESCRIPT
let some: (t<'a>, 'a => bool) => bool

some(list, f) returns true if at least one of the elements in list satisfies f, where f is a predicate: a function taking an element and returning a bool.

Examples

RESCRIPT
let isAbove100 = value => value > 100

list{101, 1, 2, 3}->List.some(isAbove100) // true

list{1, 2, 3, 4}->List.some(isAbove100) // false

every2

RESCRIPT
let every2: (t<'a>, t<'b>, ('a, 'b) => bool) => bool

every2(list1, list2, f) returns true if predicate f is true for all pairs of elements up to the shorter length (i.e. min(length(list1), length(list2)))

Examples

RESCRIPT
List.every2(list{1, 2, 3}, list{0, 1}, (a, b) => a > b) // true

List.every2(list{}, list{1}, (a, b) => a > b) // true

List.every2(list{2, 3}, list{1}, (a, b) => a > b) // true

List.every2(list{0, 1}, list{5, 0}, (a, b) => a > b) // false

some2

RESCRIPT
let some2: (t<'a>, t<'b>, ('a, 'b) => bool) => bool

some2(list1, list2, f) returns true if predicate f is true for any pair of elements up to the shorter length (i.e. min(length(list1), length(list2)))

Examples

RESCRIPT
List.some2(list{1, 2, 3}, list{0, 1}, (a, b) => a > b) // true

List.some2(list{}, list{1}, (a, b) => a > b) // false

List.some2(list{2, 3}, list{1}, (a, b) => a > b) // true

List.some2(list{0, 1}, list{5, 0}, (a, b) => a > b) // true

compareLength

RESCRIPT
let compareLength: (t<'a>, t<'a>) => Core__Ordering.t

compareLength(list1, list2) compare two lists solely by length. Returns -1. if length(list1) is less than length(list2), 0. if length(list1) equals length(list2), and 1. if length(list1) is greater than length(list2).

Examples

RESCRIPT
List.compareLength(list{1, 2}, list{3, 4, 5, 6}) // -1.

List.compareLength(list{1, 2, 3}, list{4, 5, 6}) // 0.

List.compareLength(list{1, 2, 3, 4}, list{5, 6}) // 1.

compare

RESCRIPT
let compare: ( t<'a>, t<'a>, ('a, 'a) => Core__Ordering.t, ) => Core__Ordering.t

compare(list1, list2, f) compare elements one by one f. f returns a negative number if list1 is "less than" list2, zero if list1 is "equal to" list2, a positive number if list1 is "greater than" list2.

The comparison returns the first non-zero result of f, or zero if f returns zero for all list1 and list2.

  • If all items have compared equal, but list1 is exhausted first, return -1.. (list1 is shorter).

  • If all items have compared equal, but list2 is exhausted first, return 1. (list1 is longer).

Examples

RESCRIPT
List.compare(list{3}, list{3, 7}, (a, b) => compare(a, b)) /* (-1.) */

List.compare(list{5, 3}, list{5}, (a, b) => compare(a, b)) /* 1. */

List.compare(list{1, 3, 5}, list{1, 4, 2}, (a, b) => compare(a, b)) /* (-1.) */

List.compare(list{1, 3, 5}, list{1, 2, 3}, (a, b) => compare(a, b)) /* 1. */

List.compare(list{1, 3, 5}, list{1, 3, 5}, (a, b) => compare(a, b)) /* 0. */

Please note: The total ordering of List is different from Array, for Array, we compare the length first and, only if the lengths are equal, elements one by one. For lists, we just compare elements one by one.

equal

RESCRIPT
let equal: (t<'a>, t<'a>, ('a, 'a) => bool) => bool

equal(list1, list2, f) check equality of list2 and list2 using f for equality on elements, where f is a function that returns true if items x and y meet some criterion for equality, false otherwise. equal false if length of list1 and list2 are not the same.

Examples

RESCRIPT
List.equal(list{1, 2, 3}, list{1, 2}, (a, b) => a == b) // false

List.equal(list{1, 2}, list{1, 2}, (a, b) => a == b) // true

List.equal(list{1, 2, 3}, list{(-1), (-2), (-3)}, (a, b) => abs(a) == abs(b)) // true

has

RESCRIPT
let has: (t<'a>, 'b, ('a, 'b) => bool) => bool

has(list, element, f) returns true if the list contains at least one element for which f returns `true'.

Examples

RESCRIPT
list{1, 2, 3}->List.has(2, (a, b) => a == b) // true

list{1, 2, 3}->List.has(4, (a, b) => a == b) // false

list{(-1), (-2), (-3)}->List.has(2, (a, b) => abs(a) == abs(b)) // true

getBy

RESCRIPT
let getBy: (t<'a>, 'a => bool) => option<'a>

getBy(list, f) returns Some(value) for the first value in list that satisfies the predicate function f. Returns None if no element satisfies the function.

Examples

RESCRIPT
List.getBy(list{1, 4, 3, 2}, x => x > 3) // Some(4)

List.getBy(list{1, 4, 3, 2}, x => x > 4) // None

filter

RESCRIPT
let filter: (t<'a>, 'a => bool) => t<'a>

filter(list, f) returns a list of all elements in list which satisfy the predicate function f.

Examples

RESCRIPT
let isEven = x => mod(x, 2) == 0

List.filter(list{1, 2, 3, 4}, isEven) // list{2, 4}

List.filter(list{None, Some(2), Some(3), None}, Option.isSome) // list{Some(2), Some(3)}

filterWithIndex

RESCRIPT
let filterWithIndex: (t<'a>, ('a, int) => bool) => t<'a>

filterWithIndex(list, f) returns a list of all elements in list which satisfy the predicate function f.

Examples

RESCRIPT
let isEven = x => mod(x, 2) == 0

List.filterWithIndex(list{1, 2, 3, 4}, (_x, index) => isEven(index)) // list{1, 3}

filterMap

RESCRIPT
let filterMap: (t<'a>, 'a => option<'b>) => t<'b>

filterMap(list, f) applies f to each element of list. If f returns Some(value), then value is kept in the resulting list. If f returns None, the element is not retained in the result.

Examples

RESCRIPT
let isEven = x => mod(x, 2) == 0

list{1, 2, 3, 4}
->List.filterMap(x =>
    if (isEven(x)) {
      Some(x)
    } else {
      None
    }
  ) // list{2, 4}

list{Some(1), Some(2), None}->List.filterMap(x => x) // list{1, 2}

partition

RESCRIPT
let partition: (t<'a>, 'a => bool) => (t<'a>, t<'a>)

partition(list, f) creates a pair of lists; the first list consists of all elements of list that satisfy the predicate function f, the second list consists of all elements of list that do not satisfy f.

Examples

RESCRIPT
// (elementsThatSatisfies, elementsThatDoesNotSatisfy)

List.partition(list{1, 2, 3, 4}, x => x > 2) // (list{3, 4}, list{1, 2})

unzip

RESCRIPT
let unzip: t<('a, 'b)> => (t<'a>, t<'b>)

unzip(list) takes a list of pairs and creates a pair of lists. The first list contains all the first items of the pairs, the second list contains all the second items.

Examples

RESCRIPT
List.unzip(list{(1, 2), (3, 4)}) // (list{1, 3}, list{2, 4})

List.unzip(list{("H", "W"), ("e", "o"), ("l", "r"), ("l", "l"), ("o", "d"), (" ", "!")})
// (list{"H", "e", "l", "l", "o", " "}, list{"W", "o", "r", "l", "d", "!"})

getAssoc

RESCRIPT
let getAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => option<'c>

getAssoc(list, k, f) return the second element of a pair in list where the first element equals k as per the predicate function f, or None if not found.

Examples

RESCRIPT
list{(1, "a"), (2, "b"), (3, "c")}->List.getAssoc(3, (a, b) => a == b) // Some("c")

list{(9, "morning"), (15, "afternoon"), (22, "night")}
->List.getAssoc(15, (k, item) => k /* 15 */ == item /* 9, 5, 22 */)
// Some("afternoon")

hasAssoc

RESCRIPT
let hasAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => bool

hasAssoc(list, k, f) returns true if there is a pair in list where the first element equals k as per the predicate function f.

Examples

RESCRIPT
list{(1, "a"), (2, "b"), (3, "c")}->List.hasAssoc(1, (a, b) => a == b) // true

list{(9, "morning"), (15, "afternoon"), (22, "night")}
->List.hasAssoc(25, (k, item) => k /* 25 */ == item /* 9, 5, 22 */) // false

removeAssoc

RESCRIPT
let removeAssoc: (t<('a, 'c)>, 'b, ('a, 'b) => bool) => t<('a, 'c)>

removeAssoc(list, k, f) return a list after removing the first pair whose first value is k per the equality predicate f, if not found, return a new list identical to list.

Examples

RESCRIPT
list{(1, "a"), (2, "b"), (3, "c")}->List.removeAssoc(1, (a, b) => a == b) // list{(2, "b"), (3, "c")}

list{(9, "morning"), (15, "afternoon"), (22, "night")}
->List.removeAssoc(9, (k, item) => k /* 9 */ == item /* 9, 5, 22 */)
// list{(15, "afternoon"), (22, "night")}

setAssoc

RESCRIPT
let setAssoc: (t<('a, 'c)>, 'a, 'c, ('a, 'a) => bool) => t<('a, 'c)>

setAssoc(list, k, v, f). If k exists in list by satisfying the f predicate, return a new list with the key and value replaced by the new k and v, otherwise, return a new list with the pair k, v added to the head of list.

Examples

RESCRIPT
list{(1, "a"), (2, "b"), (3, "c")}->List.setAssoc(2, "x", (a, b) => a == b) // list{(1, "a"), (2, "x"), (3, "c")}

list{(1, "a"), (3, "c")}->List.setAssoc(2, "b", (a, b) => a == b) // list{(2, "b"), (1, "a"), (3, "c")}

list{(9, "morning"), (3, "morning?!"), (22, "night")}
->List.setAssoc(15, "afternoon", (a, b) => mod(a, 12) == mod(b, 12))
// list{(9, "morning"), (15, "afternoon"), (22, "night")}

Please note: In the last example, since: 15 mod 12 equals 3 mod 12. Both the key and the value are replaced in the list.

sort

RESCRIPT
let sort: (t<'a>, ('a, 'a) => Core__Ordering.t) => t<'a>

sort(list, f) returns a sorted list.

Examples

RESCRIPT
List.sort(list{5, 4, 9, 3, 7}, Int.compare) // list{3, 4, 5, 7, 9}