Collections

All

collection.All(predicate?) -> boolean

Returns true if all elements in the collection meet a particular condition:

If a predicate is provided, returns true if the predicate returns a truthy value for all elements in the collection.
If no predicate is provided, returns true if all elements in the collection are truthy.

Parameters:

predicate (Callback |value, key| -> boolean): An optional Callback function which is called for each element in the collection. Should return a truthy value to indicate a match.

If collection is empty, returns true. If collection is nullish, returns undefined.

Example:

let numbers = [1, 3, 5, 7];
let allTruthy = numbers.All // Will be `true`
let allEven = numbers.All(|n| n % 2 == 0) // Will be `false`

Any

collection.Any(predicate?) -> boolean

Returns true if at least one element in the collection meets a particular condition:

If a predicate is provided, returns true if the predicate returns a truthy value for at least one element in the collection.
If no predicate is provided, returns true if at least one element in the collection is truthy.

The collection is searched until the first matching element is found, at which point the search stops and true is returned.

Parameters:

predicate (Callback |value, key| -> boolean): An optional Callback function which is called for each element in the collection. Should return a truthy value to indicate a match.

If collection is empty, returns false. If collection is nullish, returns undefined.

Example:

let numbers = [1, 2, 3, 4, 5];
let anyTruthy = numbers.Any // Will be `true`
let anyBiggerThan10 = numbers.Any(|n| n > 10) // Will be `false`

Clear

collection.Clear -> collection

Removes all elements from an Array or a Map. The collection is modified in place, but is also returned for convenient chaining. If given a value that is not an Array or Map, returns the original value unchanged.

ContainsKey

collection.ContainsKey(key) -> boolean

Returns true if the collection is a Map or Entity that contains the given key. In all other cases, returns false.

Count

collection.Count(predicate?) -> number

Counts the number of elements in an Array or Map which meet a condition specified by a predicate Callback function. If called without a predicate, simply returns the size of the collection.

predicate (Callback |value, key| -> boolean): An optional Callback function which is called for each element in the collection. Should return a truthy value to indicate a match.

If collection is nullish, returns undefined.

Example:

let numbers = [1, 2, 3, 4, 5];
let count = numbers.Count // Will be 5
let filteredCount = numbers.Count(|n| n % 2 == 0) // Will be 2

Filter

collection.Filter(predicate) -> array

Returns a new Array or Map containing all elements of collection which meet a condition specified by a predicate.

Parameters:

predicate (Callback |value, key| -> boolean): A Callback function which is called for each element in the collection. Should return a truthy value to indicate a match.

Returns the same type as the input collection.

If collection is an Array or Range, returns an Array.
If collection is a Map, returns a Map.
If collection is nullish, returns undefined.

Example:

let numbers = [1, 2, 3, 4, 5];
let evens = numbers.Filter(|n| n % 2 == 0)

The evens array will contain [2, 4].

FilterMap

collection.FilterMap(selector) -> array

Transforms each element of a collection using a selector function, filtering out any values where the selector returns undefined. Returns a new Array or Map containing the results.

Parameters:

selector (Callback |value, key| -> value): A Callback function which is called to transform each element in the collection. Should returned the transformed value, or undefined to filter out the element.

Will return the same type as the input collection:

If collection is an Array or Range, return an Array.
If collection is a Map, returns a Map.
If collection is nullish, returns undefined.

Examples:

let numbers = [1, 2, 3, 4, 5];
let squares = numbers.FilterMap(|n| n != 3 ? n * n : undefined)

The squares array will contain [1, 4, 16, 25].

Find

collection.Find(predicate) -> value, key

Finds the first element in the collection for which matches a condition, returning its corresponding value and key. Returns undefined for both the value and key if no match is found.

The predicate Callback function is given the value and key of each element in the collection. For Arrays or Ranges, the key is the index of the element. For Maps, the key is the key of the element. The key is passed as the second parameter so you can easily ignore it, as most of the time you will not need it. The predicate should return a truthy value to indicate a match.

If collection is not an Array, Map or Range, returns undefined for both the value and key.

Example:

let numbers = [11, 22, 33];
let value = numbers.Find(|n| n % 2 == 0) // value will be 22
let value, key = numbers.Find(|n| n % 2 == 0) // value will be 22 and key will be 1
let value, key = numbers.Find(|n, k| k == 2) // value will be 33 and key will be 2

FindMax

collection.FindMax -> value

Returns the largest element in a collection, ignoring null and undefined values. If the collection is empty, returns undefined. If collection is not an Array or Map, returns the original value unchanged.

FindMin

collection.FindMin -> value

Returns the smallest element in the collection, ignoring null and undefined values. If the collection is empty, returns undefined. If collection is not an Array or Map, returns the original value unchanged.

Insert

collection.Insert(index, value) -> collection

Inserts a given value at a particular index in an Array (collection). The Array is modified in-place, but is also returned for convenient chaining. If index is after the end of the Array, the value is appended to the end.

If collection is nullish, returns undefined.

Example:

let a = [1, 2, 3]
a.Insert(1, 4) // `a` is now [1, 4, 2, 3]

InsertAll

collection.InsertAll(index, other) -> collection

Inserts all elements from other into collection at index. Modifies collection in place, and returns it for convenient chaining.

collection (Array): The Array to modify.
index (Number): The index at which to insert the elements. If index is after the end of the Array, the values are appended to the end.
other (Array, Map or Range): The elements to insert. If other is a Map, only the values are inserted, not the keys.

If collection is nullish, does nothing and returns undefined.

Example:

let a = [1, 2, 3]
a.InsertAll(1, [4, 5]) // `a` is now [1, 4, 5, 2, 3]

Map

collection.Map(selector) -> array

Transforms each element of a collection using a selector function. Returns a new Array or Map containing the results.

The selector is given the value and key of each element in the collection. For Arrays or Ranges, the key is the index of the element. For Maps, the key is the key of the element. The key is passed as the second parameter so you can easily ignore it, as most of the time you will not need it. The selector should returned the transformed value.

Will return the same type as the input collection:

If collection is an Array or Range, return a new Array.
If collection is a Map, returns a new Map.
If collection is nullish, returns undefined.

Examples:

let numbers = [1, 2, 3, 4, 5];
let squares = numbers.Map(|n| n * n)

The squares array will contain [1, 4, 9, 16, 25].

let numbers = [1, 2, 3];
let values = numbers.Map(|n, k| n * k)

The values array will contain [0, 2, 6].

MapKeys

map.MapKeys -> keys

Returns a view of the keys of the given map. This can be used in most situations where an Array is expected, for example in a for loop. If given a value that is not a map, returns undefined.

MapValues

map.MapValues -> values

Returns a view of the values of the given map. This can be used in most situations where an Array is expected, for example in a for loop. If given a value that is not a map, returns undefined.

MaxBy

collection.MaxBy(selector) -> value

Returns the maximum value in an array, using the result of the selector function.

Parameters:

selector (Callback |value, key| -> value): A Callback function which is called for each element in the collection to choose the value to order by. If it returns undefined, the element will be skipped.

If collection is nullish, returns undefined.

MinBy

collection.MinBy(selector) -> value

Returns the minimum value in an array, using the result of the selector function.

Parameters:

selector (Callback |value, key| -> value): A Callback function which is called for each element in the collection to choose the value to order by. If it returns undefined, the element will be skipped.

If collection is nullish, returns undefined.

OrderBy

collection.OrderBy(selector) -> array

Sorts the elements of an array in ascending order, returning a new sorted array and leaving the original unchanged.

Parameters:

selector (Callback |value, key| -> value): A Callback function which is called for each element in the collection to choose the value to sort by.

If collection is nullish, returns undefined.

OrderByDesc

collection.OrderByDesc(selector) -> array

Sorts the elements of an array in descending order, returning a new sorted array and leaving the original unchanged.

Parameters:

selector (Callback |value, key| -> value): A Callback function which is called for each element in the collection to choose the value to sort by.

If collection is nullish, returns undefined.

PickRandom

this.PickRandom<Id?>(collection) -> value, key

Returns a random element from the given collection.

this (Entity): Determine's which entity's random number generator to use. If nullish, uses World. This is optional and is only used to help increase stability if a network rollback occurs. Most of the time you should just ignore this parameter.
Id: If provided, specifies which of the entity's random number generators to use. This is optional and is only used to help increase stability if a network rollback occurs. Most of the time you should ignore this parameter. See Random Number Generator Streams.
collection (Array, Map, or Range): The collection to pick from. If nullish, returns undefined.

Pop

collection.Pop -> value, key

Removes the last element from an Array or Map, and returns both its value and key. If collection is an Array, the key is the element's index. If the collection is empty or nullish, returns undefined as both the value and key.

Product

collection.Product(selector?) -> number

Multiplies all the elements in an Array or Map together.

selector (Callback |value, key| -> factor): An optional selector function that is called for each element to determine the factor to multiply by. If omitted, each element itself is used as the factor.

Only multiplies the Number values and ignores all other values. If no numbers are found in the collection, returns 1. If collection is nullish, returns undefined.

Example:

let numbers = [1, 2, 3];
let product = numbers.Product // Will be 6
let squareProduct = numbers.Product(|n| n*n) // Will be 36

Push

collection.Push(value) -> collection

Adds an element to the end of a collection. The collection is modified in-place, but is also returned for convenient chaining.

If collection is an Array, value is added as a new element.
Otherwise, returns the original collection unchanged.

PushAll

collection.PushAll(other) -> collection

Adds all elements from other to collection.

The receiving collection can be an Array or Map. It is modified in-place, but is also returned for convenient chaining.

If collection is an Array, then other can be an Array, Map or Range. All values from other will be added to collection.
If collection is a Map, then other must be also Map. The key-value pairs from other will be added to collection, overwriting any existing keys.
If collection is nullish, does nothing and returns undefined.

Examples:

let a = [1, 2, 3]
a.PushAll([4, 5, 6]) // `a` is now [1, 2, 3, 4, 5, 6]

let x = {a=1, b=2}
x.PushAll({b=3, c=4}) // `x` is now {a=1, b=3, c=4}

Range

Range(from, to) -> range

Returns a range representing all integers between from and to (exclusive). If to is less than or equal to from, returns an empty range.

RangeInclusive

RangeInclusive(from, to) -> range

Returns a range representing all integers from from to to (inclusive). If to is less than from, returns an empty range.

Remove

collection.Remove(index) -> collection

Removes the element at a particular index in an Array (collection). The Array is modified in-place, but is also returned for convenient chaining.

If index is after the end of the array, does nothing. If collection is nullish, returns undefined.

Example:

let a = [1, 2, 3]
a.Remove(1) // `a` is now [1, 3]

RemoveRange

collection.RemoveRange(index, count) -> collection

Removes count elements starting from a particular index in an Array (collection). The Array is modified in-place, but is also returned for convenient chaining.

If collection is nullish, returns undefined.

Example:

let a = [1, 2, 3, 4, 5]
a.RemoveRange(1, 2) // `a` is now [1, 4, 5]

Retain

collection.Retain(predicate?) -> collection

Filters an Array or Map in-place. Only elements that meet a condition specified by a predicate function are retained.

predicate (Callback |value, key| -> boolean): A Callback function that is called for each element to determine whether to keep it or not. Return a truthy value to keep the element, or a falsy value to remove it.

If collection is nullish, returns undefined.

Example:

let numbers = [1, 2, 3, 4, 5, 6, 7];
numbers.Retain(|n| n % 2 == 0)
// numbers is now: [2, 4, 6]

Reverse

x.Reverse -> value

Reverse(x) -> value

Reverses the contents of input.

If input is an Array or Map, the collection will be reversed in-place. The collection will also be returned for convenience.
If input is a String, a copy of the String will be returned with the characters reversed.
Otherwise, input is returned unchanged.

Shift

collection.Shift -> value, key

Removes the first element from an Array or Map, and returns both its value and key. If collection is an Array, the key is the element's index. If the collection is empty or nullish, returns undefined as both the value and key.

Shuffle

this.Shuffle<Id?>(array) -> array

Shuffles an array in place. Returns the shuffled array.

this (Entity): Determine's which entity's random number generator to use. If nullish, uses World. This is optional and is only used to help increase stability if a network rollback occurs.
Id: If provided, specifies which of the entity's random number generators to use. This is optional and is only used to help increase stability if a network rollback occurs. Most of the time you should ignore this parameter. See Random Number Generator Streams.
array (Array): The array to shuffle. If nullish, returns undefined.

Slice

collection.Slice(from, length?) -> array

Slice(collection, from, length?) -> array

Returns a new Array containing only the elements of the collection from from to from + length. Returns undefined if the input is nullish.

Parameters:

collection (Array): The collection to slice. Currently only Arrays are supported.
from (Number): The index to start slicing from. If negative, counts from the end of the array.
length (Number): The number of elements to include in the slice. If not provided, includes all elements from from to the end of the array.

Returns: A new array containing the sliced elements.

Sort

collection.Sort -> collection

Sort(collection) -> collection

Sorts the elements of an array in ascending order. The array is modified in place. It is returned to allow for chaining. If the collection is not an array, it is returned unchanged.

SortDesc

collection.SortDesc -> collection

SortDesc(collection) -> collection

Sorts the elements of an array in descending order. The array is modified in place. It is returned to allow for chaining. If the collection is not an array, it is returned unchanged.

Sum

collection.Sum(selector?) -> number

Returns the sum of all elements in an Array or Map.

selector (Callback |value, key| -> addend): An optional selector function that is called for each element to determine the addend to add to the total. If omitted, each element itself is used as the addend.

Only adds the Number values and ignores all other values. If no numbers are found in the collection, returns 0.

If collection is nullish, returns undefined.

Example:

let numbers = [1, 2, 3];
let sum = numbers.Sum // Will be 6
let squareSum = numbers.Sum(|n| n*n) // Will be 14

ToArray

collection.ToArray -> array

ToArray(collection) -> array

Returns a new Array containing all the values of the given collection. The collection can be an Array, Map, or Range. If collection is nullish, returns undefined.

ToMap

collection.ToMap -> map

ToMap(collection) -> map

Returns a new copy of a Map with the same values as the original Map. The input collection must be a Map. If the input is nullish, returns undefined.

Unshift

collection.Unshift(value) -> collection

Inserts a value at the start of an Array. The array is modified in-place, but is also returned for convenient chaining.

If collection is an Array, value is inserted at the beginning as a new element.
Otherwise, returns the original collection unchanged.

Currently, this operation takes O(n) time for Arrays, as all elements must be shifted.

VectorSum

collection.VectorSum(selector?) -> vector

Returns the sum of Vector elements in an Array or Map.

selector (Callback |value, key| -> vector): An optional selector function that is called for each element to determine the Vector to add to the total. If omitted, each element itself is used as the Vector.

Only adds the Vector values and ignores all other values. If no Vectors are found in the collection, returns @(0,0).

If collection is nullish, returns undefined.

Example:

let array = [@(1,2), @(3,4), @(5,6)];
let vectorSum = array.VectorSum // Will be @(9,12)
let doubleVectorSum = array.VectorSum(|v| 2 * v) // Will be @(18,24)

All​

Any​

Clear​

ContainsKey​

Count​

Filter​

FilterMap​

Find​

FindMax​

FindMin​

Insert​

InsertAll​

Map​

MapKeys​

MapValues​

MaxBy​

MinBy​

OrderBy​

OrderByDesc​

PickRandom​

Pop​

Product​

Push​

PushAll​

Range​

RangeInclusive​

Remove​

RemoveRange​

Retain​

Reverse​

Shift​

Shuffle​

Slice​

Sort​

SortDesc​

Sum​

ToArray​

ToMap​

Unshift​

VectorSum​

All

Any

Clear

ContainsKey

Count

Filter

FilterMap

Find

FindMax

FindMin

Insert

InsertAll

Map

MapKeys

MapValues

MaxBy

MinBy

OrderBy

OrderByDesc

PickRandom

Pop

Product

Push

PushAll

Range

RangeInclusive

Remove

RemoveRange

Retain

Reverse

Shift

Shuffle

Slice

Sort

SortDesc

Sum

ToArray

ToMap

Unshift

VectorSum