Array

Functions

arrayEquals()

arrayEquals<T>(array1, array2): boolean

Defined in: packages/isaacscript-common/src/functions/array.ts:13

Helper function for determining if two arrays contain the exact same elements. Note that this only performs a shallow comparison.

Type Parameters

T

T

Parameters

array1

readonly T[]

array2

readonly T[]

Returns

boolean

arrayRemove()

arrayRemove<T>(originalArray, …elementsToRemove): T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:36

Builds a new array based on the original array without the specified element(s). Returns the new array. If the specified element(s) are not found in the array, it will simply return a shallow copy of the array.

If there is more than one matching element in the array, this function will remove all of them.

This function is variadic, meaning that you can specify N arguments to remove N elements.

Type Parameters

T

T

Parameters

originalArray

readonly T[]

elementsToRemove

…readonly T[]

Returns

T[]

arrayRemoveAllInPlace()

arrayRemoveAllInPlace<T>(array, …elementsToRemove): boolean

Defined in: packages/isaacscript-common/src/functions/array.ts:65

Removes all of the specified element(s) from the array. If the specified element(s) are not found in the array, this function will do nothing.

This function is variadic, meaning that you can specify N arguments to remove N elements.

If there is more than one matching element in the array, this function will remove every matching element. If you want to only remove the first matching element, use the arrayRemoveInPlace function instead.

Type Parameters

T

T

Parameters

array

T[]

elementsToRemove

…readonly T[]

Returns

boolean

True if one or more elements were removed, false otherwise.

arrayRemoveIndex()

arrayRemoveIndex<T>(originalArray, …indexesToRemove): T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:93

Shallow copies and removes the elements at the specified indexes from the array. Returns the copied array. If the specified indexes are not found in the array, it will simply return a shallow copy of the array.

This function is variadic, meaning that you can specify N arguments to remove N elements.

Type Parameters

T

T

Parameters

originalArray

readonly T[]

indexesToRemove

…readonly int[]

Returns

T[]

arrayRemoveIndexInPlace()

arrayRemoveIndexInPlace<T>(array, …indexesToRemove): T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:118

Removes the elements at the specified indexes from the array. If the specified indexes are not found in the array, this function will do nothing.

This function is variadic, meaning that you can specify N arguments to remove N elements.

Type Parameters

T

T

Parameters

array

T[]

indexesToRemove

…readonly int[]

Returns

T[]

The removed elements. This will be an empty array if no elements were removed.

arrayRemoveInPlace()

arrayRemoveInPlace<T>(array, …elementsToRemove): T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:159

Removes the specified element(s) from the array. If the specified element(s) are not found in the array, this function will do nothing.

This function is variadic, meaning that you can specify N arguments to remove N elements.

If there is more than one matching element in the array, this function will only remove the first matching element. If you want to remove all of the elements, use the arrayRemoveAllInPlace function instead.

Type Parameters

T

T

Parameters

array

T[]

elementsToRemove

…readonly T[]

Returns

T[]

The removed elements. This will be an empty array if no elements were removed.

arrayToString()

arrayToString(array): string

Defined in: packages/isaacscript-common/src/functions/array.ts:178

Parameters

array

readonly unknown[]

Returns

string

combineArrays()

combineArrays<T>(…arrays): T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:196

Helper function to combine two or more arrays. Returns a new array that is the composition of all of the specified arrays.

This function is variadic, meaning that you can specify N arguments to combine N arrays. Note that this will only perform a shallow copy of the array elements.

Type Parameters

T

T

Parameters

arrays

…readonly readonly T[][]

Returns

T[]

copyArray()

copyArray<T>(oldArray, numElements?): T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:215

Helper function to perform a shallow copy.

Type Parameters

T

T

Parameters

oldArray

readonly T[]

The array to copy.

numElements?

int

Optional. If specified, will only copy the first N elements. By default, the entire array will be copied.

Returns

T[]

emptyArray()

emptyArray(array): void

Defined in: packages/isaacscript-common/src/functions/array.ts:233

Helper function to remove all of the elements in an array in-place.

Parameters

array

unknown[]

Returns

void

filterMap()

filterMap<OldT, NewT>(array, func): readonly NewT[]

Defined in: packages/isaacscript-common/src/functions/array.ts:248

Helper function to perform a filter and a map at the same time. Similar to Array.map, provide a function that transforms a value, but return undefined if the value should be skipped. (Thus, this function cannot be used in situations where undefined can be a valid array element.)

This function is useful because the Array.map method will always produce an array with the same amount of elements as the original array.

This is named filterMap after the Rust function: https://doc.rust-lang.org/std/iter/struct.FilterMap.html

Type Parameters

OldT

OldT

NewT

NewT

Parameters

array

readonly OldT[]

func

(element) => NewT | undefined

Returns

readonly NewT[]

getArrayCombinations()

getArrayCombinations<T>(array, includeEmptyArray, min?, max?): readonly readonly T[][]

Defined in: packages/isaacscript-common/src/functions/array.ts:288

Helper function to get all possible combinations of the given array. This includes the combination of an empty array.

For example, if this function is provided an array containing 1, 2, and 3, then it will return an array containing the following arrays:

[] (if includeEmptyArray is set to true)
[1]
[2]
[3]
[1, 2]
[1, 3]
[2, 3]
[1, 2, 3]

From: https://github.com/firstandthird/combinations/blob/master/index.js

Type Parameters

T

T

Parameters

array

readonly T[]

The array to get the combinations of.

includeEmptyArray

boolean

Whether to include an empty array in the combinations.

min?

int

Optional. The minimum number of elements to include in each combination. Default is 1.

max?

int

Optional. The maximum number of elements to include in each combination. Default is the length of the array.

Returns

readonly readonly T[][]

getArrayDuplicateElements()

getArrayDuplicateElements<T>(array): readonly T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:322

Helper function to get the duplicate elements in an array. Only one element for each value will be returned. The elements will be sorted before they are returned.

Type Parameters

T

T extends string | number

Parameters

array

readonly T[]

Returns

readonly T[]

getArrayIndexes()

getArrayIndexes(array): readonly int[]

Defined in: packages/isaacscript-common/src/functions/array.ts:348

Helper function to get an array containing the indexes of an array.

For example, an array of ["Apple", "Banana"] would return an array of [0, 1].

Note that normally, you would use the Object.keys method to get the indexes of an array, but due to implementation details of TypeScriptToLua, this results in an array of 1 through N (instead of an array of 0 through N -1).

Parameters

array

readonly unknown[]

Returns

readonly int[]

getHighestArrayElement()

getHighestArrayElement(array): number | undefined

Defined in: packages/isaacscript-common/src/functions/array.ts:356

Helper function to get the highest value in an array. Returns undefined if there were no elements in the array.

Parameters

array

readonly number[]

Returns

number | undefined

getLowestArrayElement()

getLowestArrayElement(array): number | undefined

Defined in: packages/isaacscript-common/src/functions/array.ts:378

Helper function to get the lowest value in an array. Returns undefined if there were no elements in the array.

Parameters

array

readonly number[]

Returns

number | undefined

getRandomArrayElement()

getRandomArrayElement<T>(array, seedOrRNG, exceptions?): T

Defined in: packages/isaacscript-common/src/functions/array.ts:408

Helper function to get a random element from the provided array.

If you want to get an unseeded element, you must explicitly pass undefined to the seedOrRNG parameter.

Type Parameters

T

T

Parameters

array

readonly T[]

The array to get an element from.

seedOrRNG

RNG | Seed | undefined

The Seed or RNG object to use. If an RNG object is provided, the RNG.Next method will be called. If undefined is provided, it will default to a random seed.

exceptions?

readonly T[] = []

Optional. An array of elements to skip over if selected.

Returns

T

getRandomArrayElementAndRemove()

getRandomArrayElementAndRemove<T>(array, seedOrRNG, exceptions?): T

Defined in: packages/isaacscript-common/src/functions/array.ts:444

Helper function to get a random element from the provided array. Once the random element is decided, it is then removed from the array (in-place).

If you want to get an unseeded element, you must explicitly pass undefined to the seedOrRNG parameter.

Type Parameters

T

T

Parameters

array

T[]

The array to get an element from.

seedOrRNG

RNG | Seed | undefined

The Seed or RNG object to use. If an RNG object is provided, the RNG.Next method will be called. If undefined is provided, it will default to a random seed.

exceptions?

readonly T[] = []

Optional. An array of elements to skip over if selected.

Returns

T

getRandomArrayIndex()

getRandomArrayIndex(array, seedOrRNG, exceptions?): int

Defined in: packages/isaacscript-common/src/functions/array.ts:472

Helper function to get a random index from the provided array.

If you want to get an unseeded index, you must explicitly pass undefined to the seedOrRNG parameter.

Parameters

array

readonly unknown[]

The array to get the index from.

seedOrRNG

RNG | Seed | undefined

The Seed or RNG object to use. If an RNG object is provided, the RNG.Next method will be called. If undefined is provided, it will default to a random seed.

exceptions?

readonly int[] = []

Optional. An array of indexes that will be skipped over when getting the random index. Default is an empty array.

Returns

int

includes()

includes<T, TupleElement>(array, searchElement): searchElement is TupleElement

Defined in: packages/isaacscript-common/src/functions/array.ts:492

Similar to the Array.includes method, but works on a widened version of the array.

This is useful when the normal Array.includes produces a type error from an array that uses an as const assertion.

Type Parameters

T

T

TupleElement

TupleElement

Parameters

array

readonly TupleElement[]

searchElement

WidenLiteral<T>

Returns

searchElement is TupleElement

isArray()

isArray(object, ensureContiguousValues?): object is unknown[]

Defined in: packages/isaacscript-common/src/functions/array.ts:511

Since Lua uses tables for every non-primitive data structure, it is non-trivial to determine if a particular table is being used as an array. isArray returns true if:

the table contains all numerical indexes that are contiguous, starting at 1
the table has no keys (i.e. an “empty” table)

Parameters

object

unknown

The object to analyze.

ensureContiguousValues?

boolean = true

Optional. Whether the Lua table has to have all contiguous keys in order to be considered an array. Default is true.

Returns

object is unknown[]

isArrayContiguous()

isArrayContiguous(array): boolean

Defined in: packages/isaacscript-common/src/functions/array.ts:556

Helper function to see if every element in the array is N + 1.

For example, [2, 3, 4] would return true, and [2, 3, 5] would return false.

Parameters

array

readonly int[]

Returns

boolean

isArrayElementsUnique()

isArrayElementsUnique(array): boolean

Defined in: packages/isaacscript-common/src/functions/array.ts:574

Helper function to check if all the elements of an array are unique within that array.

Under the hood, this is performed by converting the array to a set.

Parameters

array

readonly unknown[]

Returns

boolean

isArrayInArray()

isArrayInArray<T>(arrayToMatch, parentArray): boolean

Defined in: packages/isaacscript-common/src/functions/array.ts:580

Checks if an array is in the provided 2-dimensional array.

Type Parameters

T

T

Parameters

arrayToMatch

readonly T[]

parentArray

readonly readonly T[][]

Returns

boolean

setAllArrayElements()

setAllArrayElements<T>(array, value): void

Defined in: packages/isaacscript-common/src/functions/array.ts:589

Helper function to set every element in an array to a specific value.

Type Parameters

T

T

Parameters

array

T[]

value

T

Returns

void

shuffleArray()

shuffleArray<T>(originalArray, seedOrRNG): T[]

Defined in: packages/isaacscript-common/src/functions/array.ts:608

Shallow copies and shuffles the array using the Fisher-Yates algorithm. Returns the copied array.

If you want an unseeded shuffle, you must explicitly pass undefined to the seedOrRNG parameter.

From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array

Type Parameters

T

T

Parameters

originalArray

readonly T[]

The array to shuffle.

seedOrRNG

RNG | Seed | undefined

The Seed or RNG object to use. If an RNG object is provided, the RNG.Next method will be called. If undefined is provided, it will default to a random seed.

Returns

T[]

shuffleArrayInPlace()

shuffleArrayInPlace(array, seedOrRNG): void

Defined in: packages/isaacscript-common/src/functions/array.ts:632

Shuffles the provided array in-place using the Fisher-Yates algorithm.

If you want an unseeded shuffle, you must explicitly pass undefined to the seedOrRNG parameter.

From: https://stackoverflow.com/questions/2450954/how-to-randomize-shuffle-a-javascript-array

Parameters

array

unknown[]

The array to shuffle.

seedOrRNG

RNG | Seed | undefined

The Seed or RNG object to use. If an RNG object is provided, the RNG.Next method will be called. If undefined is provided, it will default to a random seed.

Returns

void

sumArray()

sumArray(array): number

Defined in: packages/isaacscript-common/src/functions/array.ts:650

Helper function to sum every value in an array together.

Parameters

array

readonly number[]

Returns

number

swapArrayElements()

swapArrayElements(array, i, j): void

Defined in: packages/isaacscript-common/src/functions/array.ts:657

Helper function to swap two different array elements. (The elements will be swapped in-place.)

Parameters

array

unknown[]

i

number

j

number

Returns

void