@barchart/common-js/types/lang/array.d.ts

Library of common JavaScript utilities

/**
* Utilities for working with arrays.
*
* @public
* @module lang/array
*/
/**
 * Returns the unique items from an array, where the unique
 * key is determined via a strict equality check.
 *
 * @static
 * @param {Array} a
 * @returns {Array}
 */
export function unique(a: any[]): any[];
/**
 * Returns the unique items from an array, where the unique
 * key is determined by a delegate.
 *
 * @static
 * @param {Array} a
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {Array}
 */
export function uniqueBy(a: any[], keySelector: Function): any[];
/**
 * Splits array into groups and returns an object (where the properties have
 * arrays). Unlike the indexBy function, there can be many items which share
 * the same key.
 *
 * @static
 * @param {Array} a
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {object}
 */
export function groupBy(a: any[], keySelector: Function): object;
/**
 * Splits array into groups and returns an array of arrays where the items of each
 * nested array share a common key.
 *
 * @static
 * @param {Array} a
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {Array}
 */
export function batchBy(a: any[], keySelector: Function): any[];
/**
 * Splits array into groups and returns an object (where the properties are items from the
 * original array). Unlike the {@link array#groupBy} function, only one item can have a
 * given key value.
 *
 * @static
 * @param {Array} a
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {object}
 */
export function indexBy(a: any[], keySelector: Function): object;
/**
 * Returns a new array containing all but the first item.
 *
 * @static
 * @param {Array} a
 * @returns {Array}
 */
export function dropLeft(a: any[]): any[];
/**
 * Returns a new array containing all but the last item.
 *
 * @static
 * @param {Array} a
 * @returns {Array}
 */
export function dropRight(a: any[]): any[];
/**
 * Returns the first item from an array, or an undefined value, if the
 * array is empty.
 *
 * @static
 * @param {Array} a
 * @returns {*|undefined}
 */
export function first(a: any[]): any | undefined;
/**
 * Returns the last item from an array, or an undefined value, if the
 * array is empty.
 *
 * @static
 * @param {Array} a
 * @returns {*|undefined}
 */
export function last(a: any[]): any | undefined;
/**
 * Returns a copy of an array, replacing any item that is itself an array
 * with the item's items.
 *
 * @static
 * @param {Array} a
 * @param {boolean=} recursive - If true, all nested arrays will be flattened.
 * @returns {Array}
 */
export function flatten(a: any[], recursive?: boolean | undefined): any[];
/**
 * Breaks an array into smaller arrays, returning an array of arrays.
 *
 * @static
 * @param {Array} a
 * @param {number} size - The maximum number of items per partition.
 * @returns {Array<Array>}
 */
export function partition(a: any[], size: number): Array<any[]>;
/**
 * Set difference operation, returning any item in "a" that is not
 * contained in "b" (using strict equality).
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @returns {Array}
 */
export function difference(a: any[], b: any[]): any[];
/**
 * Set difference operation, returning any item in "a" that is not
 * contained in "b" (where the uniqueness is determined by a delegate).
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {Array}
 */
export function differenceBy(a: any[], b: any[], keySelector: Function): any[];
/**
 * Set symmetric difference operation (using strict equality). In
 * other words, this is the union of the differences between the
 * sets.
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @returns {Array}
 */
export function differenceSymmetric(a: any[], b: any[]): any[];
/**
 * Set symmetric difference operation, where the uniqueness is determined by a delegate.
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {Array}
 */
export function differenceSymmetricBy(a: any[], b: any[], keySelector: Function): any[];
/**
 * Set union operation (using strict equality).
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @returns {Array}
 */
export function union(a: any[], b: any[]): any[];
/**
 * Set union operation, where the uniqueness is determined by a delegate.
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {Array}
 */
export function unionBy(a: any[], b: any[], keySelector: Function): any[];
/**
 * Set intersection operation (using strict equality).
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @returns {Array}
 */
export function intersection(a: any[], b: any[]): any[];
/**
 * Set intersection operation, where the uniqueness is determined by a delegate.
 *
 * @static
 * @param {Array} a
 * @param {Array} b
 * @param {Function} keySelector - A function that returns a unique key for an item.
 * @returns {Array}
 */
export function intersectionBy(a: any[], b: any[], keySelector: Function): any[];
/**
 * Removes the first item from an array which matches a predicate.
 *
 * @static
 * @public
 * @template T
 * @param {T[]} a
 * @param {(value: T, index: number, array: T[]) => boolean} predicate
 * @returns {boolean}
 */
export function remove<T>(a: T[], predicate: (value: T, index: number, array: T[]) => boolean): boolean;
/**
 * Inserts an item into an array using a binary search is used to determine the
 * proper point for insertion and returns the same array.
 *
 * @static
 * @public
 * @param {Array} a
 * @param {*} item
 * @param {(a: any, b: any) => number} comparator
 * @returns {Array}
 */
export function insert(a: any[], item: any, comparator: (a: any, b: any) => number): any[];
/**
 * Performs a binary search to locate an item within an array.
 *
 * @param {*[]} a
 * @param {*} key
 * @param {Function} comparator
 * @param {number=} start
 * @param {number=} end
 * @returns {*|null}
 */
export function binarySearch(a: any[], key: any, comparator: Function, start?: number | undefined, end?: number | undefined): any | null;