@tempots/std/array.d.ts

Std library for TypeScript. Natural complement to the Tempo libraries.

import { Compare, Maybe, Nothing, Primitive } from './domain';
/**
 * Applies a function to each element of an array and returns a new array with the results.
 *
 * @typeParam A - The type of the elements in the input array.
 * @typeParam B - The type of the elements in the output array.
 * @param arr - The input array.
 * @param f - The function to apply to each element.
 * @returns The new array with the results of applying the function to each element.
 * @public
 */
export declare const mapArray: <A, B>(arr: A[], f: (a: A, index: number) => B) => B[];
/**
 * Applies a mapping function to each element of an array and flattens the result.
 *
 * @param arr - The input array.
 * @param f - The mapping function to apply to each element of the array.
 * @returns A new array with the flattened result of applying the mapping function to each element of the input array.
 * @typeParam A - The type of the elements in the input array.
 * @typeParam B - The type of the elements in the resulting flattened array.
 * @public
 */
export declare const flatMapArray: <A, B>(arr: A[], f: (a: A) => B[]) => B[];
/**
 * Returns the first element of an array, or `undefined` if the array is empty.
 *
 * @param arr - The input array.
 * @returns The first element of the array, or `undefined` if the array is empty.
 * @typeParam A - The type of elements in the array.
 * @public
 */
export declare const arrayHead: <A>(arr: A[]) => Maybe<A>;
/**
 * Returns a new array containing all elements of the input array except for the first element.
 *
 * @param arr - The input array.
 * @returns A new array containing all elements of the input array except for the first element.
 * @public
 */
export declare const arrayTail: <A>(arr: A[]) => A[];
/**
 * Checks if two arrays are equal based on a custom equality function.
 *
 * @typeParam T - The type of elements in the arrays.
 * @param a - The first array.
 * @param b - The second array.
 * @param equality - The custom equality function to compare elements.
 * @returns Returns `true` if the arrays are equal, `false` otherwise.
 * @public
 */
export declare const areArraysEqual: <T>(a: T[], b: T[], equality: (a: T, b: T) => boolean) => boolean;
/**
 * Checks if an array is empty.
 *
 * @param arr - The array to check.
 * @returns `true` if the array is empty, `false` otherwise.
 * @public
 */
export declare const isArrayEmpty: <T>(arr: T[]) => arr is [];
/**
 * Checks if an array has values.
 *
 * @param arr - The array to check.
 * @returns `true` if the array has values, `false` otherwise.
 * @public
 */
export declare const arrayHasValues: <T>(arr: T[]) => arr is [T, ...T[]];
/**
 * Filters the elements of an array based on a predicate function.
 *
 * @typeParam T - The type of the elements in the array.
 * @param arr - The array to filter.
 * @param predicate - The predicate function used to filter the elements.
 * @returns The filtered array.
 * @public
 */
export declare const filterArray: <T>(arr: T[], predicate: (v: T) => boolean) => T[];
/**
 * Applies a mapping function to each element of an array and returns a new array
 * containing the mapped values, excluding any `null` or `undefined` values.
 *
 * @typeParam A - The type of the elements in the input array.
 * @typeParam B - The type of the elements in the output array.
 * @param arr - The input array.
 * @param f - The mapping function to apply to each element.
 * @returns The new array containing the mapped values.
 * @public
 */
export declare const filterMapArray: <A, B>(arr: A[], f: (a: A, index: number) => Maybe<B>) => B[];
/**
 * Filters out null and undefined values from an array.
 *
 * @typeParam T - The type of elements in the array.
 * @param arr - The array to filter.
 * @returns The filtered array.
 * @public
 */
export declare const filterNullsFromArray: <T>(arr: Array<T | Nothing>) => T[];
/**
 * Flattens a two-dimensional array into a one-dimensional array.
 *
 * @param arr - The two-dimensional array to flatten.
 * @returns The flattened one-dimensional array.
 * @typeParam T - The type of elements in the array.
 * @public
 */
export declare const flattenArray: <T>(arr: T[][]) => T[];
/**
 * Applies a function to each element of an array, accumulating the result from left to right.
 *
 * @typeParam T - The type of the array elements.
 * @typeParam B - The type of the accumulator.
 * @param arr - The array to iterate over.
 * @param f - The function to apply to each element.
 * @param b - The initial value of the accumulator.
 * @returns The accumulated result.
 * @public
 */
export declare const foldLeftArray: <T, B>(arr: T[], f: (acc: B, curr: T) => B, b: B) => B;
/**
 * Checks if all elements in an array satisfy a given predicate.
 *
 * @param arr - The array to check.
 * @param predicate - The predicate function to apply to each element.
 * @returns `true` if all elements satisfy the predicate, `false` otherwise.
 * @typeParam T - The type of elements in the array.
 * @public
 */
export declare const allElements: <T>(arr: T[], predicate: (v: T) => boolean) => boolean;
/**
 * Checks if any element in the array satisfies the given predicate.
 *
 * @param arr - The array to check.
 * @param predicate - The predicate function to apply to each element.
 * @returns `true` if any element satisfies the predicate, `false` otherwise.
 * @typeParam T - The type of elements in the array.
 * @public
 */
export declare const anyElement: <T>(arr: T[], predicate: (v: T) => boolean) => boolean;
/**
 * Applies a function to each element in an array.
 *
 * @typeParam T - The type of elements in the array.
 * @param arr - The array to iterate over.
 * @param f - The function to apply to each element.
 * @public
 */
export declare const forEachElement: <T>(arr: T[], f: (v: T) => void) => void;
/**
 * Concatenates multiple arrays into a single array.
 *
 * @param arrs - The arrays to concatenate.
 * @returns The concatenated array.
 * @typeParam A - The type of elements in the arrays.
 * @public
 */
export declare const concatArrays: <A>(...arrs: A[][]) => A[];
/**
 * Compares two arrays based on their lengths and element values.
 *
 * @typeParam A - The type of elements in the arrays.
 * @param a - The first array to compare.
 * @param b - The second array to compare.
 * @param comparef - The compare function to use for comparing the elements of the arrays.
 * @param shorterFirst - Specifies whether shorter arrays should be considered smaller. Defaults to true.
 * @returns A compare function that can be used to compare arrays.
 * @public
 */
export declare const compareArrays: <A>(a: A[], b: A[], comparef: Compare<A>, shorterFirst?: boolean) => number;
/**
 * Sorts an array in place using the provided compare function.
 *
 * @typeParam A - The type of elements in the array.
 * @param arr - The array to be sorted.
 * @param compare - The compare function used to determine the order of the elements.
 * @returns The sorted array.
 * @public
 */
export declare const sortArray: <A>(arr: A[], compare: Compare<A>) => A[];
/**
 * Generates an array of values by applying a function to each index.
 *
 * @param length - The length of the resulting array.
 * @param f - The function to apply to each index. It takes the index as a parameter and returns the corresponding value.
 * @returns An array of values generated by applying the function to each index.
 * @public
 */
export declare const generateArray: <A>(length: number, f: (index: number) => A) => A[];
/**
 * Generates an array of numbers in a specified range.
 *
 * @param length - The length of the array to generate.
 * @param startAt - The starting value of the range. Default is 0.
 * @returns An array of numbers in the specified range.
 * @public
 */
export declare const generateSequenceArray: (length: number, startAt?: number) => number[];
/**
 * Creates a new array with the specified length and fills it with the provided value.
 *
 * @typeParam A - The type of the elements in the array.
 * @param length - The length of the new array.
 * @param value - The value to fill the array with.
 * @returns A new array filled with the specified value.
 * @public
 */
export declare const createFilledArray: <A>(length: number, value: A) => A[];
/**
 * Returns an array containing only the distinct primitive values from the input array.
 *
 * @typeParam T - The type of the input array elements.
 * @param values - The input array.
 * @returns An array containing only the distinct primitive values from the input array.
 * @public
 */
export declare const uniquePrimitives: <T extends Primitive>(values: T[]) => T[];
/**
 * Returns an array of distinct elements from the input array based on the provided predicate.
 *
 * @typeParam T - The type of elements in the input array.
 * @param values - The input array.
 * @param predicate - The predicate function used to determine uniqueness.
 * @returns An array of distinct elements.
 * @public
 */
export declare const uniqueByPrimitive: <T>(values: T[], predicate: (a: T) => string | number | symbol) => T[];
/**
 * Removes the first occurrence of an item from an array.
 *
 * @typeParam A - The type of the array elements.
 * @param arr - The array from which to remove the item.
 * @param item - The item to remove from the array.
 * @returns `true` if the item was found and removed, `false` otherwise.
 * @public
 */
export declare const removeOneFromArray: <A>(arr: A[], item: A) => boolean;
/**
 * Removes all occurrences of an item from an array.
 *
 * @typeParam A - The type of the array elements.
 * @param arr - The array from which to remove the item.
 * @param item - The item to remove from the array.
 * @returns `true` if at least one occurrence was found and removed, `false` otherwise.
 * @public
 */
export declare const removeAllFromArray: <A>(arr: A[], item: A) => boolean;
/**
 * Removes the first occurrence in an array that satisfy the given predicate.
 *
 * @typeParam A - The type of elements in the array.
 * @param arr - The array from which elements will be removed.
 * @param predicate - The predicate function used to determine which elements to remove.
 * @returns `true` if at least one element was removed, `false` otherwise.
 * @public
 */
export declare const removeOneFromArrayByPredicate: <A>(arr: A[], predicate: (a: A) => boolean) => boolean;
/**
 * Removes all occurrences in an array that satisfy the given predicate.
 *
 * @typeParam A - The type of elements in the array.
 * @param arr - The array from which elements will be removed.
 * @param predicate - The predicate function used to determine which elements to remove.
 * @returns `true` if at least one element was removed, `false` otherwise.
 * @public
 */
export declare const removeAllFromArrayByPredicate: <A>(arr: A[], predicate: (a: A) => boolean) => boolean;
/**
 * Converts an IterableIterator to an array.
 *
 * @param it - The IterableIterator to convert.
 * @returns An array containing the values from the IterableIterator.
 * @public
 */
export declare const arrayOfIterableIterator: <A>(it: IterableIterator<A>) => A[];
/**
 * Represents the different operations that can be performed on an array.
 *
 * @public
 */
export type ArrayDiffOperations<T> = {
    removals: Array<{
        at: number;
        qt: number;
    }>;
    swaps: Array<{
        from: number;
        to: number;
    }>;
    inserts: Array<{
        at: number;
        values: T[];
    }>;
};
/**
 * Calculates the difference operations between two arrays based on a key function.
 *
 * @typeParam T - The type of elements in the arrays.
 * @typeParam K - The type of the key used to compare elements.
 * @param from - The source array.
 * @param to - The target array.
 * @param getKey - The key function used to compare elements.
 * @returns The difference operations between the two arrays.
 * @public
 */
export declare const arrayDiffOperations: <T, K>(from: T[], to: T[], getKey: (v: T) => K) => ArrayDiffOperations<T>;
/**
 * Applies a series of operations to an array and returns the modified array.
 *
 * @typeParam T - The type of elements in the array.
 * @param operations - The operations to apply.
 * @param start - The initial array.
 * @returns The modified array after applying the operations.
 * @public
 */
export declare const applyArrayDiffOperations: <T>(operations: ArrayDiffOperations<T>, start: T[]) => T[];
/**
 * Joins an array of values into a string using a conjunction and separator.
 *
 * @param arr - The array of values to join.
 * @param conjunction - The conjunction to use between the second-to-last and last value. Default is ' and '.
 * @param separator - The separator to use between each value. Default is ', '.
 * @returns The joined string.
 * @public
 */
export declare const joinArrayWithConjunction: <A>(arr: A[], conjunction?: string, separator?: string) => string;
/**
 * Assigns ranks to the elements in the array based on the provided compare function.
 * The ranks are assigned in ascending order, with the lowest value receiving a rank of 0.
 * If there are duplicate values, the rank of the duplicates can be incremented or not based on the `incrementDuplicates` parameter.
 *
 * @typeParam T - The type of elements in the array.
 * @param array - The array to rank.
 * @param compare - The compare function used to determine the order of elements.
 * @param incrementDuplicates - Whether to increment the rank of duplicate values.
 * @returns An array of ranks corresponding to the elements in the input array.
 * @public
 */
export declare const rankArray: <T>(array: T[], compare: (a: T, b: T) => number, incrementDuplicates?: boolean) => number[];