isaacscript-common/dist/functions/array.d.ts

Helper functions and features for IsaacScript mods.

import type { WidenLiteral } from "../types/WidenLiteral";
/**
 * Helper function for determining if two arrays contain the exact same elements. Note that this
 * only performs a shallow comparison.
 */
export declare function arrayEquals<T>(array1: readonly T[], array2: readonly T[]): boolean;
/**
 * 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.
 */
export declare function arrayRemove<T>(originalArray: readonly T[], ...elementsToRemove: readonly T[]): T[];
/**
 * 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.
 *
 * @returns True if one or more elements were removed, false otherwise.
 */
export declare function arrayRemoveAllInPlace<T>(array: T[], ...elementsToRemove: readonly T[]): boolean;
/**
 * 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.
 *
 * @returns The removed elements. This will be an empty array if no elements were removed.
 */
export declare function arrayRemoveInPlace<T>(array: T[], ...elementsToRemove: readonly T[]): T[];
/**
 * 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.
 */
export declare function arrayRemoveIndex<T>(originalArray: readonly T[], ...indexesToRemove: readonly int[]): T[];
/**
 * 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.
 *
 * @returns The removed elements. This will be an empty array if no elements were removed.
 */
export declare function arrayRemoveIndexInPlace<T>(array: T[], ...indexesToRemove: readonly int[]): T[];
export declare function arrayToString(array: readonly unknown[]): string;
/**
 * 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.
 */
export declare function combineArrays<T>(...arrays: ReadonlyArray<readonly T[]>): T[];
/**
 * Helper function to perform a shallow copy.
 *
 * @param oldArray The array to copy.
 * @param numElements Optional. If specified, will only copy the first N elements. By default, the
 *                    entire array will be copied.
 */
export declare function copyArray<T>(oldArray: readonly T[], numElements?: int): T[];
/** Helper function to remove all of the elements in an array in-place. */
export declare function emptyArray(array: unknown[]): void;
/**
 * 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
 */
export declare function filterMap<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => NewT | undefined): readonly NewT[];
/**
 * 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
 *
 * @param array The array to get the combinations of.
 * @param includeEmptyArray Whether to include an empty array in the combinations.
 * @param min Optional. The minimum number of elements to include in each combination. Default is 1.
 * @param max Optional. The maximum number of elements to include in each combination. Default is
 *            the length of the array.
 */
export declare function getArrayCombinations<T>(array: readonly T[], includeEmptyArray: boolean, min?: int, max?: int): ReadonlyArray<readonly T[]>;
/**
 * 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.
 */
export declare function getArrayDuplicateElements<T extends number | string>(array: readonly T[]): readonly T[];
/**
 * 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).
 */
export declare function getArrayIndexes(array: readonly unknown[]): readonly int[];
/**
 * Helper function to get the highest value in an array. Returns undefined if there were no elements
 * in the array.
 */
export declare function getHighestArrayElement(array: readonly number[]): number | undefined;
/**
 * Helper function to get the lowest value in an array. Returns undefined if there were no elements
 * in the array.
 */
export declare function getLowestArrayElement(array: readonly number[]): number | undefined;
/**
 * 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.
 *
 * @param array The array to get an element from.
 * @param seedOrRNG 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.
 * @param exceptions Optional. An array of elements to skip over if selected.
 */
export declare function getRandomArrayElement<T>(array: readonly T[], seedOrRNG: Seed | RNG | undefined, exceptions?: readonly T[]): T;
/**
 * 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.
 *
 * @param array The array to get an element from.
 * @param seedOrRNG 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.
 * @param exceptions Optional. An array of elements to skip over if selected.
 */
export declare function getRandomArrayElementAndRemove<T>(array: T[], seedOrRNG: Seed | RNG | undefined, exceptions?: readonly T[]): T;
/**
 * 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.
 *
 * @param array The array to get the index from.
 * @param seedOrRNG 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.
 * @param exceptions Optional. An array of indexes that will be skipped over when getting the random
 *                   index. Default is an empty array.
 */
export declare function getRandomArrayIndex(array: readonly unknown[], seedOrRNG: Seed | RNG | undefined, exceptions?: readonly int[]): int;
/**
 * 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.
 */
export declare function includes<T, TupleElement extends WidenLiteral<T>>(array: readonly TupleElement[], searchElement: WidenLiteral<T>): searchElement is TupleElement;
/**
 * 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)
 *
 * @param object The object to analyze.
 * @param ensureContiguousValues Optional. Whether the Lua table has to have all contiguous keys in
 *                               order to be considered an array. Default is true.
 */
export declare function isArray(object: unknown, ensureContiguousValues?: boolean): object is unknown[];
/**
 * 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.
 */
export declare function isArrayContiguous(array: readonly int[]): boolean;
/**
 * 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.
 */
export declare function isArrayElementsUnique(array: readonly unknown[]): boolean;
/** Checks if an array is in the provided 2-dimensional array. */
export declare function isArrayInArray<T>(arrayToMatch: readonly T[], parentArray: ReadonlyArray<readonly T[]>): boolean;
/** Helper function to set every element in an array to a specific value. */
export declare function setAllArrayElements<T>(array: T[], value: T): void;
/**
 * 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
 *
 * @param originalArray The array to shuffle.
 * @param seedOrRNG 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.
 */
export declare function shuffleArray<T>(originalArray: readonly T[], seedOrRNG: Seed | RNG | undefined): T[];
/**
 * 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
 *
 * @param array The array to shuffle.
 * @param seedOrRNG 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.
 */
export declare function shuffleArrayInPlace(array: unknown[], seedOrRNG: Seed | RNG | undefined): void;
/** Helper function to sum every value in an array together. */
export declare function sumArray(array: readonly number[]): number;
/**
 * Helper function to swap two different array elements. (The elements will be swapped in-place.)
 */
export declare function swapArrayElements(array: unknown[], i: number, j: number): void;
//# sourceMappingURL=array.d.ts.map