# 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:// 1List.Get(List.Build(1,2,3,4,5), 2)// Result:// 3List.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"})``