# Collection

Library of functions for the collection type.

## Functions​

### Avg​

Computes the average value of a collection of numbers.

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

### Build​

Builds a new collection.

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

### Contains​

Tests if some value is contained in a collection.

Syntax:
``Collection.Contains(collection: collection, value: anything)``
##### Parameters​
• `collection`: The collection.

• `value`: The value to search for.

##### Returns​
• `bool`: True if the value is contained in the collection, false otherwise.
Example:
``Collection.Contains(Collection.Build(1,2,3), 2)// Result:// true``

### Count​

Counts the number of elements in a collection.

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

### Distinct​

Removes duplicate elements of a collection.

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

### Empty​

Creates an empty collection.

Syntax:
``Collection.Empty(type: type)``
##### Parameters​
• `type`: The type of the elements of the empty collection.
##### Returns​
• `collection`: The empty collection.
Example:
``Collection.Empty(type int)``

### EquiJoin​

Joins two collections with an equality condition.

Syntax:
``Collection.EquiJoin(first: collection, second: collection, firstKey: function, secondKey: function)``
##### Parameters​
• `first`: The first collection to join.

• `second`: The second collection to join.

• `firstKey`: The join condition function, which receives a row with elements from the first collection 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 collection and returns the key to perform the equality join condition on.

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

`EquiJoin` is a more efficient and scalable than `Join`, so use it when possible.

### Exists​

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

Syntax:
``Collection.Exists(collection: collection, predicate: function)``
##### Parameters​
• `collection`: The collection.

• `predicate`: The function predicate.

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

### Explode​

Moves elements of a nested collection into elements of the parent collection.

Syntax:
``Collection.Explode(collection: collection, nested: collection)``
##### Parameters​
• `collection`: The collection to explode elements to.

• `nested`: The collection to explode elements from.

##### Returns​
• `collection`: The collection with elements from the nested collection exploded into elements of the parent collection.
Example:
``// Suppose you have the following JSON data:// [//   {//     "title": "Less than 2",//     "numbers": [{"v": 0}, {"v": 1}]//   },//   {//     "title": "More than 2",//     "numbers": [{"v": 3}, {"v": 4}]//   }// ]//let data = Json.Read("example.json")in  Collection.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 collection that satisfy a predicate.

Syntax:
``Collection.Filter(collection: collection, predicate: function)``
##### Parameters​
• `collection`: The collection to filter.

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

##### Returns​
• `collection`: The filtered collection.
Example:
``Collection.Filter(  Collection.Build(1,2,3),  v -> v >= 2)// Result:// [2,3]``

### FindFirst​

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

Syntax:
``Collection.FindFirst(collection: collection, predicate: function)``
##### Parameters​
• `collection`: The collection.

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

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

### FindLast​

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

Syntax:
``Collection.FindLast(collection: collection, predicate: function)``
##### Parameters​
• `collection`: The collection.

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

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

### First​

Selects the first element of a collection.

Syntax:
``Collection.First(collection: collection)``
##### Parameters​
• `collection`: The collection to select the first element from.
##### Returns​
• `number`: The first element in the collection.
Example:
``Collection.First(Collection.Build(2, 3, 1))// Result:// 2``

### From​

Builds a collection from the items of a list.

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

### GroupBy​

Partitions the input collection according to a key function.

Syntax:
``Collection.GroupBy(collection: collection, predicate: function)``
##### Parameters​
• `collection`: The collection to partition.

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

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

### Join​

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

Syntax:
``Collection.Join(first: collection, second: collection, condition: function)``
##### Parameters​
• `first`: The first collection to join.

• `second`: The second collection to join.

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

##### Returns​
• `collection`: A new collection of records that includes the fields from both input collections.
Example:
``let  first = Collection.Build( {v: 1}, {v: 2}, {v: 3} ),  second = Collection.Build( {n: 1, name: "One"}, {n: 2, name: "Two"} )in  Collection.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 collection that isn't a collection of records, appear in the joined record// with an automatically generated field name (here: _1).let  first = Collection.Build(1,2,3),  second = Collection.Build( {n: 1, name: "One"}, {n: 2, name: "Two"} )in  Collection.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 collection.

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

### Max​

Finds the largest element in a collection.

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

### Min​

Finds the smallest element in a collection.

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

### MkString​

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

Syntax:
``Collection.MkString(collection: collection, start: optional string, sep: optional string, end: optional string)``
##### Parameters​
• `collection`: A collection.

• `start`: The starting string.

• `sep`: The separator string.

• `end`: The ending string.

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

### OrderBy​

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

Syntax:
``Collection.OrderBy(collection: collection, key: function ..., order: string ...)``
##### Parameters​
• `collection`: The collection to order.

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

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

##### Returns​
• `collection`: The ordered collection.
Example:
``Collection.OrderBy(movies, m -> m.country, "ASC", m -> m.budget, "DESC")``

### Sum​

Sums all elements of a collection.

Syntax:
``Collection.Sum(collection: collection)``
##### Parameters​
• `collection`: The collection to sum elements from.
##### Returns​
• `number`: The sum of all elements in the collection.
Example:
``Collection.Sum(Collection.Build(3, 1, 2))// Result:// 6``

### Take​

Selects first N elements of a collection.

Syntax:
``Collection.Take(collection: collection, n: int)``
##### Parameters​
• `collection`: The collection to select the first N elements from.

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

##### Returns​
• `collection`: The first N elements in the collection.
Example:
``Collection.Take(Collection.Build(3, 1, 2), 3)// Result:// [3, 1]``

### Transform​

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

Syntax:
``Collection.Transform(collection: collection, function: function)``
##### Parameters​
• `collection`: The collection to read.

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

##### Returns​
• `collection`: The new collection.
Example:
``Collection.Transform(  Collection.Build(1,2,3),  v -> v * 10)// Result:// [10, 20, 30]``

### Union​

Merge, i.e. union, the input collections into one.

Syntax:
``Collection.Union(collection: collection ...)``
##### Parameters​
• `collection`: The collections to union.
##### Returns​
• `collection`: The union of the collections.
Example:
``Collection.Union([1, 2, 3], [4, 5, 6])// Result:// [1, 2, 3, 4, 5, 6]``

### Zip​

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

Syntax:
``Collection.Zip(collection1: collection, collection2: collection)``
##### Parameters​
• `collection1`: A collection.

• `collection2`: A collection.

##### Returns​
• `collection`: A collection of pairs of elements from the two collections.
Example:
``Collection.Zip(  Collection.Build(1,2,3),  Collection.Build("a", "b", "c"))// Result:// Collection.Build({1, "a"}, {2, "b"}, {3, "c"})``