Standard Library: List

Check whether every value in a list of booleans is true.

List.all([])
List.all([true, true, true])
List.all([true, true, false])

true
true
false

Check whether any value in a list of booleans is true.

List.any([])
List.any([false, false, false])
List.any([false, false, true])

false
false
true

Get the average of numbers.

List.average([10, 50, 60])

40

Sort list in ascending order and get the first count values.

List.bottom([3, 1, 4, 1, 5, 9, 2, 6, 5, 4], 5)

[1, 1, 2, 3, 4]

Split list into chunks of length count (the final chunk may. be shorter).

List.chunks([1, 2, 3, 4, 5, 6, 7, 8], 3)

[[1, 2, 3], [4, 5, 6], [7, 8]]

Count the number of times value appears in list.

List.count([1, 9, 9, 6], 9)

2

Get the counts and total shares for the values in list. Returns a table with columns value, count, and share, sorted descending by count.

List.countAll(["NY", "CA", "IL", "TX", "AZ", "PA", "TX", "CA", "TX", "FL"])

┌───────┬───────┬───────┐
│ value │ count │ share │ x 7
├───────┼───────┼───────┤
│ TX    │     3 │   0.3 │
│ CA    │     2 │   0.2 │
│ NY    │     1 │   0.1 │
│ IL    │     1 │   0.1 │
│ AZ    │     1 │   0.1 │
│ PA    │     1 │   0.1 │
│ FL    │     1 │   0.1 │
└───────┴───────┴───────┘

Remove the first count elements from list.

drop(["a", "b", "c", "d", "e"], 3)

["d", "e"]

(Accessible as a global through Overloads.drop)

Remove the last count elements from list.

List.dropLast(["a", "b", "c", "d", "e"], 3)

["a", "b"]

Get the values in list that satisfy condition.

List.filter([1, 2, 3, 4], Math.isEven)

[2, 4]

Note that this can also be accomplished using the filter ? operator:

[1, 2, 3, 4] ? Math.isEven

[2, 4]

Get the first value in list that satisfies condition, or none if no match is present.

List.find([7, 8, 9, 10], Math.isEven)
List.find([7, 8, 9, 10], fn(n) n < 5 end)

8
none

Return the value at index in list.

List.get(["a", "b", "c", "d"], 2)

"c"

Note that this can also be accomplished using the index [] operator:

["a", "b", "c", "d"][2]

"c"

Group each value in list according to func(value).

List.groupBy(
  ["apple", "pear", "peach", "banana", "plum", "apricot", "orange"],
  fn(word) take(word, 1) end
)

{
  a: ["apple", "apricot"],
  p: ["pear", "peach", "plum"],
  b: ["banana"],
  o: ["orange"],
}

Check whether list contains value.

List.has(["a", "b", "c"], "b")
List.has(["a", "b", "c"], "d")

true
false

Note that this can also be accomplished using the in operator.

"b" in ["a", "b", "c"]
"d" in ["a", "b", "c"]

true
false

Check whether list contains every value in values, where values is a list, set, or table. Duplicate items must appear at least as many times in list as they do in values.

List.hasAll(["a", "b", "c"], ["b", "c"])
List.hasAll(["a", "b", "c"], ["d", "c"])

List.hasAll(["a", "a", "a"], ["a", "a"])
List.hasAll(["a"], ["a", "a"])

true
false
true
false

Get the index of the first occurence of value in list, or none if value does not appear in list.

List.indexOf([1, 9, 9, 6], 9)
List.indexOf([1, 9, 9, 6], 0)

1
none

Check whether list is empty.

isEmpty([])
isEmpty(["a", "b", "c", "d"])

true
false

(Accessible as a global through Overloads.isEmpty)

Return the number of elements in list.

len(["a", "b", "c", "d"])

4

(Accessible as a global through Overloads.len)

Transform each value in list using func.

List.map([1, 2, 3, 4], fn(n) n * 2 end)

[2, 4, 6, 8]

Note that this can also be accomplished using the map $ operator:

[1, 2, 3, 4] $ arg * 2

[2, 4, 6, 8]

Get the maximum of list. See the docs for sort for requirements for list and details on the ranking process.

List.max([-7, 1, 50])

50

(Accessible as a global through Overloads.max)

Get all the items in list for which func(item) is maximized. See the docs for sortBy for requirements for func and details on the ranking process.

List.maxAll(
  ["apple", "pear", "peach", "banana", "plum", "apricot", "orange"],
  len
)

["apricot"]

Get the first item of a non-empty list for which func(item) is maximized. See the docs for sortBy for requirements for func and details on the ranking process.

List.maxBy(
  ["apple", "pear", "peach", "banana", "plum", "apricot", "orange"],
  len
)

"apricot"

Get the maximum of list or none if list is empty. See the docs for sort for requirements for list and details on the ranking process.

List.maxNone([-7, 1, 50])
List.maxNone([])

50
none

Get the median of numbers.

List.median([1, 1, 1, 2, 3, 4, 5])
List.median([7, 9])

2
8

Merge (flatten) lists into a single list.

l1 = ["a", "b"]
l2 = ["c", "d", "e"]
List.merge([l1, l2])

["a", "b", "c", "d", "e"]

Note that lists can also be merged using the + operator.

l1 + l2

["a", "b", "c", "d", "e"]

Get the minimum of list. See the docs for sort for requirements for list and details on the ranking process.

List.min([-7, 1, 50])

-7

(Accessible as a global through Overloads.min)

Get all the items in list for which func(item) is minimized. See the docs for sortBy for requirements for func and details on the ranking process.

List.minAll(
  ["apple", "pear", "peach", "banana", "plum", "apricot", "orange"],
  len
)

["pear", "plum"]

Get the first item of a non-empty list for which func(item) is minimized. See the docs for sortBy for requirements for func and details on the ranking process.

List.minBy(
  ["apple", "pear", "peach", "banana", "plum", "apricot", "orange"],
  len
)

"pear"

Get the minimum of list or none if list is empty. See the docs for sort for requirements for list and details on the ranking process.

List.minNone([-7, 1, 50])
List.minNone([])

-7
none

Scale a list of non-negative numbers so they sum to 1. Requires that sum(numbers) > 0.

List.normalize([5, 7, 8])

[0.25, 0.35, 0.4]

Get a list containing each value in values. values may be a set, table, or list. If values is a table then List.of(values) returns a list of the table's rows.

s = Set.of(["a", "b", "c", "d"])
List.of(s)

t = Table.of({ name: ["Ducky", "Clementine"], type: ["dog", "bird"] })
List.of(t)

["a", "b", "c", "d"]
[{ name: "Ducky", type: "dog" }, { name: "Clementine", type: "bird" }]

Scale a list of non-negative numbers so they sum to 100. Requires that sum(numbers) > 0.

List.percents([5, 7, 8])

[25, 35, 40]

Remove the last element from list.

List.pop(["a", "b", "c", "d", "e"])

["a", "b", "c", "d"]

Add value to the end of list.

push(["a", "b", "c"], "d")

["a", "b", "c", "d"]

(Accessible as a global through Overloads.push)

Get a list of integers between 0 and limit - 1, inclusive. limit must be an integer. If limit < 1 then [] is returned.

range(10)

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Remove all occurences of value from list.

remove([1, 2, none, 3, 4, none], none)

[1, 2, 3, 4]

(Accessible as a global through Overloads.remove)

Remove all occurences of each value in values from list, where values is a list, set, or table.

List.removeAll([1, 2, none, 3, 4, 0, none], [none, 0])

[1, 2, 3, 4]

Create a list containing value repeated count times.

List.repeat("0", 5)

["0", "0", "0", "0", "0"]

_Note that this can also be accomplished using the _ operator*:

["0"] * 5

["0", "0", "0", "0", "0"]

Reverse list.

reverse(["a", "b", "c", "d"])

["d", "c", "b", "a"]

(Accessible as a global through Overloads.reverse)

Replace the element at index in list with value.

List.set(["a", "b", "d", "d"], 2, "c")

["a", "b", "c", "d"]

Note that if you want to update an existing variable, you could also use variable assignment:

letters = ["a", "b", "d", "d"]
letters[2] = "c"

letters =
["a", "b", "c", "d"]

Sort a list in ascending order, where list contains numbers, strings, booleans, or nones. All non-none values in list must be of the same type. Any none values will be placed at the end of the resulting list.

sort([3, 1, 4, 1, 5, 9, 2, 6, 5, 4])
sort(["apple", "pear", "peach", "banana", "plum", "apricot", "orange", none])
sort([true, false, true, false])

[1, 1, 2, 3, 4, 4, 5, 5, 6, 9]
["apple", "apricot", "banana", "orange", "peach", "pear", "plum", none]
[false, false, true, true]

Sort list in ascending order using ranker(value) as the sort key. The ranker function must return a number, string, boolean, or none. All non-none values returned by ranker must be of the same type. Values for which ranker returns none will be placed at the end of the resulting list.

sortBy(
  ["apple", "pear", "peach", "banana", "plum", "apricot", "orange"],
  len
)

["pear", "plum", "apple", "peach", "banana", "orange", "apricot"]

(Accessible as a global through Overloads.sortBy)

Sort a list in descending order. See the docs for sort for requirements for list and details on the sorting process.

sortDesc([3, 1, 4, 1, 5, 9, 2, 6, 5, 4])
sortDesc(["apple", "pear", "peach", "banana", "plum", "apricot", "orange", none])
sortDesc([true, false, true, false])

[9, 6, 5, 5, 4, 4, 3, 2, 1, 1]
["plum", "pear", "peach", "orange", "banana", "apricot", "apple", none]
[true, true, false, false]

Sort list in descending order using ranker(value) as the sort key. See the docs for sortBy for requirements for ranker and details on the sorting process.

sortDescBy(
  ["apple", "pear", "peach", "banana", "plum", "apricot", "orange"],
  len
)

["apricot", "banana", "orange", "apple", "peach", "pear", "plum"]

(Accessible as a global through Overloads.sortDescBy)

Get a list of integers between from and to, inclusive. from and to must be integers.

span(1, 10)
span(2, -2)

[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
[2, 1, 0, -1, -2]

Remove count elements from list starting at index, and replace them with the list values.

List.splice(["a", "b", "c", "d", "e", "f"], 3, 2, ["x", "y", "z"])

["a", "b", "c", "x", "y", "z", "f"]

Get the sum of numbers.

sum([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])

55

(Accessible as a global through Overloads.sum)

Swap the elements at indexA and indexB in list.

List.swap(["a", "c", "b", "d"], 1, 2)

["a", "b", "c", "d"]

Get the first count elements from list.

take(["a", "b", "c", "d", "e"], 3)

["a", "b", "c"]

(Accessible as a global through Overloads.take)

Get the last count elements from list.

List.takeLast(["a", "b", "c", "d", "e"], 3)

["c", "d", "e"]

Sort list in descending order and get the first count values.

List.top([3, 1, 4, 1, 5, 9, 2, 6, 5, 4], 5)

[9, 6, 5, 5, 4]

Remove duplicate values from list, keeping only the first occurrence of each value.

List.unique(["NY", "CA", "IL", "TX", "AZ", "PA", "TX", "CA", "TX", "FL"])

["NY", "CA", "IL", "TX", "AZ", "PA", "FL"]