Skip to main content

Collections

All​

collection.All -> boolean

Returns true if all elements in the collection are truthy, otherwise false. If the collection is empty, returns true. If given a value that is not an array or map, returns whether the value is truthy.

Any​

collection.Any -> boolean

Returns true if any elements in the collection are truthy, otherwise false. If the collection is empty, returns false. If given a value that is not an array or map, returns whether the value is truthy.

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 |value, key| { } -> 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.

The predicate 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 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 |value, key| { } -> array

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

The predicate 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.

Will return 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 |value, key| { } -> 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.

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, 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 |value, key| { } -> 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 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.
  • 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 |value, key| { } -> 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 |element| { } -> value

Returns the maximum value in an array, using the result of the selector function. The selector is a function that takes an element of the collection and returns a value. The selector is called for each element of the collection.

If collection is nullish, returns undefined.

MinBy​

collection.MinBy |element| { } -> value

Returns the minimum value in an array, using the result of the selector function. The selector is a function that takes an element of the collection and returns a value. The selector is called for each element of the collection. If selector returns undefined for any element, that element is skipped.

If collection is nullish, returns undefined.

OrderBy​

collection.OrderBy |element| { } -> array

Sorts the elements of an array in ascending order, returning a new sorted array and leaving the original unchanged. The selector is a function that takes an element of the collection and returns a value to sort by. The selector is called for each element of the collection.

If collection is nullish, returns undefined.

OrderByDesc​

collection.OrderByDesc |element| { } -> array

Sorts the elements of an array in descending order, returning a new sorted array and leaving the original unchanged. The selector is a function that takes an element of the collection and returns a value to sort by. The selector is called for each element of the collection.

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.

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.

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 -> number

Returns the sum of all numbers in the collection. All non-number elements are ignored. If the collection is empty, returns 0. If collection is not a collection, returns the original value if it is a number, otherwise returns 0.

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 -> vector

Returns the sum of all Vector elements in the collection. All non-Vector elements are ignored. If the collection is empty, returns @(0,0). If collection is not a collection, returns the original value if it is a Vector, otherwise returns @(0,0).