/**
 * Helper functions that have to do with arrays.
 *
 * @module
 */
import type { WidenLiteral } from "../types/WidenLiteral.js";
/**
 * Helper function to copy a two-dimensional array. Note that the sub-arrays will only be shallow
 * copied (using the spread operator).
 */
export declare function arrayCopyTwoDimensional<T>(array: ReadonlyArray<readonly T[]>): ReadonlyArray<readonly T[]>;
/**
 * 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[]): readonly 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
 * one. 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[]): readonly 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 an asynchronous filter. The vanilla `Array.filter` method does not
 * wait for promises (and treats them as truthy), so this function runs the predicate on all
 * elements concurrently, awaits the results, and then filters the original array.
 *
 * Usage:
 *
 * ```ts
 * const results = await filterAsync(things, async (thing) => await filterFunc(thing));
 * ```
 *
 * (This is an abstraction around `Promise.all`.)
 */
export declare function filterAsync<T>(array: readonly T[], predicate: (element: T, index: number, array: readonly T[]) => Promise<boolean>): Promise<readonly T[]>;
/**
 * 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[], predicate: (element: OldT) => NewT | undefined): readonly NewT[];
/**
 * 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
 *
 * This is the asynchronous version, which can be used like this:
 *
 * ```ts
 * const results = await asyncFilterMap(things, someFunc);
 * ```
 *
 * (This is an abstraction around `Promise.all`.)
 */
export declare function filterMapAsync<OldT, NewT>(array: readonly OldT[], predicate: (element: OldT, index: number, array: readonly OldT[]) => Promise<NewT | undefined>): Promise<readonly NewT[]>;
/**
 * Helper function to get a random element from the provided array.
 *
 * Note that this will only work with arrays that do not contain values of `undefined`, since the
 * function uses `undefined` as an indication that the corresponding element does not exist.
 *
 * @param array The array to get an element from.
 * @param exceptions Optional. An array of elements to skip over if selected.
 */
export declare function getRandomArrayElement<T>(array: readonly T[], exceptions?: readonly T[]): T;
/**
 * Helper function to get a random index from the provided array.
 *
 * @param array The array to get the index from.
 * @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[], exceptions?: readonly number[]): number;
/**
 * 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;
/**
 * Similar to the `Array.includes` method, but accepts a variadic amount of search elements.
 *
 * @returns True if any of the elements are found, false otherwise.
 */
export declare function includesAny<T>(array: readonly T[], ...searchElements: readonly T[]): boolean;
/** A wrapper around `Array.isArray` that narrows to `unknown[]` instead of `any[]`. */
export declare function isArray(variable: unknown): variable is unknown[];
/** Helper function to check every value of an array to see if it is a boolean. */
export declare function isArrayBoolean(variable: unknown): variable is boolean[];
/** Helper function to check every value of an array to see if it is a number. */
export declare function isArrayNumber(variable: unknown): variable is number[];
/** Helper function to check every value of an array to see if it is an object. */
export declare function isArrayObject(variable: unknown): variable is Array<Record<string, unknown>>;
/** Helper function to check every value of an array to see if it is a string. */
export declare function isArrayString(variable: unknown): variable is string[];
/**
 * Helper function to perform an asynchronous map. The vanilla `Array.map` method does not wait for
 * promises, resulting in an array of promises rather than the resolved values. This function runs
 * the callback on all elements concurrently, awaits the results, and returns the mapped array.
 *
 * You can also use this function to simply run an asynchronous function on each element of an array
 * concurrently.
 *
 * Usage:
 *
 * ```ts
 * const results = await mapAsync(things, async (thing) => await mapFunc(thing));
 * ```
 *
 * (This is an abstraction around `Promise.all`.)
 */
export declare function mapAsync<T, U>(array: readonly T[], callback: (element: T, index: number, array: readonly T[]) => Promise<U>): Promise<readonly U[]>;
/** Initializes an array with all elements containing the specified default value. */
export declare function newArray<T>(length: number, value: T): readonly T[];
/** Helper function to sum every value in an array together. */
export declare function sumArray(array: readonly number[]): number;
/**
 * Helper function to filter out non-unique elements from an array and sort it. Under the hood, this
 * converts the array to a `Set` and then back to an sorted array.
 */
export declare function unique<T>(array: readonly T[]): readonly T[];
//# sourceMappingURL=array.d.ts.map