Skip to main content

List

Library of functions for the list type.

Functions​

Avg​

Computes the average value of a list of numbers.

Syntax:
List.Avg(list: list ...)
Parameters​
  • list: The list to compute the average on.
Returns​
  • decimal: The average value of the list.
Example:
List.Avg(List.Build(1,2,3,4,5))
// Result:
// 3

Build​

Builds a new list.

Syntax:
List.Build(values: anything ...)
Parameters​
  • values: Values to add to the list.
Returns​
  • list: The new list.
Example:
List.Build(1,2,3,4,5)
// Result:
// [1,2,3,4,5]

Contains​

Tests if some value is contained in a list.

Syntax:
List.Contains(list: list, value: anything)
Parameters​

  • list: The list.

  • value: The value to search for.

Returns​
  • bool: True if the value is contained in the list, false otherwise.
Example:
List.Contains(Lust.Build(1,2,3), 2)
// Result:
// true

Count​

Counts the number of elements in a list.

Syntax:
List.Count(list: list)
Parameters​
  • list: The list to count elements.
Returns​
  • long: The number of elements in the list.
Example:
List.Count(
  List.Build(1,2,3)
)
// Result:
// 3

Distinct​

Removes duplicate elements of a list.

Syntax:
List.Distinct(list: list)
Parameters​
  • list: The list to remove duplicate elements from.
Returns​
  • list: The new list.
Example:
List.Distinct(
  List.Build(1,2,2,3,3,3)
)
// Result:
// [1, 2, 3]

Empty​

Creates an empty list.

Syntax:
List.Empty(type: type)
Parameters​
  • type: The type of the elements of the empty list.
Returns​
  • list: The empty list.
Example:
List.Empty(type int)

EquiJoin​

Joins two lists with an equality condition.

Syntax:
List.EquiJoin(first: list, second: list, firstKey: function, secondKey: function)
Parameters​

  • first: The first list to join.

  • second: The second list to join.

  • firstKey: The join condition function, which receives a row with elements from the first list and returns the key to perform the equality join condition on.

  • secondKey: The join condition function, which receives a row with elements from the second list and returns the key to perform the equality join condition on.

Returns​
  • list: A new list built from joining both lists.
Example:
let
  first = [ {v: 1}, {v: 2}, {v: 3} ],
  second = [ {n: 1, name: "One"}, {n: 2, name: "Two"} ]
in
  List.EquiJoin(first, second, a -> a.v, b -> b.n)
// Result:
// [ { v: 1, n: 1, name: "One" }, { v: 2, n: 2, name: "Two" } ]

Exists​

Tests whether a predicate holds for at least one element of a list.

Syntax:
List.Exists(list: list, predicate: function)
Parameters​

  • list: The list.

  • predicate: The function predicate.

Returns​
  • bool: A boolean indicating whether the predicate holds for at least one element of the list.
Example:
List.Exists(
  List.Build(1,2,3),
  v -> v >= 2
) // true
// Result:
// true

Explode​

Moves elements of a nested list into elements of the parent list

Syntax:
List.Explode(list: list, nested: list)
Parameters​

  • list: The list to explode elements to.

  • nested: The list to explode elements from.

Returns​
  • The list with elements exploded.
Example:

let data = [
  {
    title: "Less than 2",
    numbers: [{v: 0}, {v: 1}]
  },
  {
    title: "More than 2",
    numbers: [{v: 3}, {v: 4}]
  }
]
in
  List.Explode(data, r -> r.numbers)
// Result:
// [
//   {
//     title: "Less than 2",
//     numbers: [{v: 0}, {v: 1}],
//     v: 0,
//   },
//   {
//     title: "Less than 2",
//     numbers: [{v: 0}, {v: 1}],
//     v: 1,
//   },
//   {
//     title: "More than 2",
//     numbers: [{v: 3}, {v: 4}],
//     v: 3
//   },
//   {
//     title: "More than 2",
//     numbers: [{v: 3}, {v: 4}],
//     v: 4
//   }
// ]

Filter​

Selects all elements of a list that satisfy a predicate.

Syntax:
List.Filter(list: list, predicate: function)
Parameters​

  • list: The list to filter.

  • predicate: The function predicate, which receives an element of a list and must return true/false whether the element is to be seleected or not.

Returns​
  • list: The filtered list.
Example:
List.Filter(
  List.Build(1,2,3),
  v -> v >= 2
)
// Result:
// List.Build(2, 3)

FindFirst​

Returns the first element of a list that satisfies a predicate.

Syntax:
List.FindFirst(list: list, predicate: function)
Parameters​

  • list: The list.

  • predicate: The function predicate to apply to the elements.

Returns​
  • The first element in the list that satisfies the predicate.
Example:
List.FindFirst(
  List.Build(1,2,3),
  v -> v >= 2
)
// Result:
// 2

FindLast​

Returns the last element of a list that satisfies a predicate.

Syntax:
List.FindLast(list: list, predicate: function)
Parameters​

  • list: The list.

  • predicate: The function predicate to apply to the elements.

Returns​
  • The last element in the list that satisfies the predicate.
Example:
List.FindLast(
  List.Build(1,2,3),
  v -> v <= 2
)
// Result:
// 2

First​

Selects the first element of a list.

Syntax:
List.First(list: list)
Parameters​
  • list: The list to select the first element from.
Returns​
  • The first element in the list.
Example:
List.First(List.Build(2, 3, 1))
// Result:
// 2

From​

Builds a list from the items of a collection.

Syntax:
List.From(collection: collection)
Parameters​
  • collection: The collection to build the list from.
Returns​
  • list: The list built from the collection.
Example:
List.From(Collection.Build(1, 2, 3))
// Result:
// List.Build(1, 2, 3)

Get​

Selects an element from a list by index.

Syntax:
List.Get(list: list, index: int)
Parameters​

  • list: The list to select the element from.

  • index: The index (starting from zero) of the element to select.

Returns​
  • anything: The selected element.
Example:
List.Get(List.Build(1,2,3,4,5), 0)
// Result:
// 1

List.Get(List.Build(1,2,3,4,5), 2)
// Result:
// 3

List.Get(List.Build(1,2,3,4,5), 100)
// Result:
// index out of bounds
note

Selecting an element out of bounds returns an "index out of bounds" error.

GroupBy​

Partitions the input list according to a key function.

Syntax:
List.GroupBy(list: list, predicate: function)
Parameters​

  • list: The list to partition.

  • predicate: The partition function, which receives an elements of the list and returns the key to partition it by.

Returns​
  • list: A list of pairs, where the first element is the key and the second element is the list of elements with that key.

Join​

Joins two lists given a join condition, into a list of records that includes the fields from both input lists.

Syntax:
List.Join(first: list, second: list, condition: function)
Parameters​

  • first: The first list to join.

  • second: The second list to join.

  • condition: The join condition function, which applies to a pair of elements, one from each list, and returns true if they should be joined.

Returns​
  • list: A new list of records that includes the fields from both input lists.
Example:
let
  first = List.Build( {v: 1}, {v: 2}, {v: 3} ),
  second = List.Build( {n: 1, name: "One"}, {n: 2, name: "Two"} )
in
  List.Join(first, second, (row1, row2) -> row1.v == row2.n)
// Result:
// [ { v: 1, n: 1, name: "One" }, { v: 2, n: 2, name: "Two" } ]

// items of a list that isn't a list of records, appear in the joined record
// with an automatically generated field name (here: _1).
let
  first = [1,2,3],
  second = [{n: 1, name: "One"}, {n: 2, name: "Two"}]
in
  List.Join(first, second, (v, row2) -> v == row2.n)
// Result:
// [ { _1: 1, n: 1, name: "One" }, { _1: 2, n: 2, name: "Two" } ]

Last​

Selects the last element of a list.

Syntax:
List.Last(list: list)
Parameters​
  • list: The list to select the last element from.
Returns​
  • The last element in the list.
Example:
List.Last(List.Build(3, 1, 2))
// Result:
// 2

Max​

Finds the largest element in a list.

Syntax:
List.Max(list: list)
Parameters​
  • list: The list to find the largest element from.
Returns​
  • number: The largest element in the list.
Example:
List.Max(List.Build(2, 3, 1))
// Result:
// 3

Min​

Finds the smallest element in a list.

Syntax:
List.Min(list: list)
Parameters​
  • list: The list to find the smallest element from.
Returns​
  • number: The smallest element in the list.
Example:
List.Min(List.Build(3, 1, 2))
// Result:
// 1

MkString​

Concatenates all elements of a list in a string using start, end, and separator strings.

Syntax:
List.MkString(list: list, start: optional string, sep: optional string, end: optional string)
Parameters​

  • list: A list.

  • start: The starting string.

  • sep: The separator string.

  • end: The ending string.

Returns​
  • string: A string containing all elements of the list separated by the separator string.
Example:
List.MkString(
  List.Build("a", "b", "c"),
  start="(", sep=":", end=")")"
// Result:
// "(a:b:c)"

OrderBy​

Orders this list according to the key functions and orderings passed as parameters.

Syntax:
List.OrderBy(list: list, key: function ..., order: string ...)
Parameters​

  • list: The list to order.

  • key: The key ordering function, which receives an element of the list and returns the key.

  • order: The order: "ASC" or "DESC".

Returns​
  • list: The ordered list.
Example:
List.OrderBy(movies, m -> m.country, "ASC", m -> m.budget, "DESC")"

Sum​

Sums up all elements of a list.

Syntax:
List.Sum(list: list)
Parameters​
  • list: The list to sum elements from.
Returns​
  • int: The sum of all elements in the list.
Example:
List.Sum(List.Build(3, 1, 2))
// Result:
// 6

Take​

Selects first N elements of a list.

Syntax:
List.Take(list: list, n: int)
Parameters​

  • list: The list to select the first N elements from.

  • n: The number of elements to select from the list.

Returns​
  • list: The list of the first N elements.
Example:
List.Take(List.Build(3, 1, 2), 3)
// Result:
// List.Build(3, 1)

Transform​

Builds a new list by applying a function to each element of a list.

Syntax:
List.Transform(list: list, function: function)
Parameters​

  • list: The list to read.

  • function: The mapping function, which receives an element of the list and returns a new element for the new list.

Returns​
  • list: The transformed list.
Example:
List.Transform(
  List.Build(1,2,3),
  v -> v * 10
)
// Result:
// List.Build(10, 20, 30)

Union​

Merge the input lists into one.

Syntax:
List.Union(list: list ...)
Parameters​
  • list: The lists to union.
Returns​
  • list: The union of the lists.
Example:
List.Union([1, 2, 3], [4, 5, 6])
// Result:
// [1, 2, 3, 4, 5, 6]

Zip​

Turns two lists into one by combining their corresponding elements in pairs until the shortest list is exhausted.

Syntax:
List.Zip(list1: list, list2: list)
Parameters​

  • list1: A list.

  • list2: A list.

Returns​
  • list: A list of pairs of elements from the two lists.
Example:
List.Zip(
  List.Build(1,2,3),
  List.Build("a", "b", "c")
)
// Result:
// List.Build({1, "a"}, {2, "b"}, {3, "c"})