@rimbu/base/dist/cjs/arr.d.cts

Utilities to implement Rimbu collections

import { TraverseState, Update, type ArrayNonEmpty } from '@rimbu/common';
/**
 * Internal helper that appends a value using the modern immutable `toSpliced` API.
 * @internal
 * @typeparam T - the array element type
 * @param array - the source array (not mutated)
 * @param value - the value to append
 * @returns a new non-empty array with the value at the end
 */
export declare function _appendNew<T>(array: readonly T[], value: T): ArrayNonEmpty<T>;
/**
 * Internal helper that appends a value by cloning and pushing (legacy fallback).
 * @internal
 * @typeparam T - the array element type
 * @param array - the source array (not mutated)
 * @param value - the value to append
 * @returns a new non-empty array with the value at the end
 */
export declare function _appendOld<T>(array: readonly T[], value: T): ArrayNonEmpty<T>;
/**
 * Returns a copy of the array with the given value appended.
 * Chooses an implementation depending on environment capabilities.
 * @typeparam T - the array element type
 * @param array - the source array (not mutated)
 * @param value - the value to append
 * @returns a new array with the value at the end
 */
export declare const append: typeof _appendNew;
/**
 * Returns the concatenation of two arrays, reusing an input array when the other is empty.
 * @typeparam T - the array element type
 * @param first - the first array
 * @param second - the second array
 * @returns a new array containing all elements of both arrays (or one of the originals if the other is empty)
 */
export declare function concat<T>(first: readonly T[], second: readonly T[]): readonly T[];
/**
 * Internal helper to create a reversed copy using modern `toReversed` with optional slicing.
 * @internal
 */
export declare function _reverseNew<T>(array: readonly T[], start?: number, end?: number): T[];
/**
 * Internal helper to create a reversed copy using manual iteration (legacy fallback).
 * @internal
 */
export declare function _reverseOld<T>(array: readonly T[], start?: number, end?: number): T[];
/**
 * Returns a copy of the array (or a slice) with elements in reversed order.
 * @typeparam T - array element type
 * @param array - the source array
 * @param start - optional start index (inclusive)
 * @param end - optional end index (inclusive)
 */
export declare const reverse: typeof _reverseNew;
/**
 * Performs the given function for each element of the array, optionally in reverse order.
 * Halting is supported through the provided `TraverseState`.
 * @typeparam T - element type
 * @param array - the source array
 * @param f - callback receiving (value, sequential index, halt)
 * @param state - traversal state (created if omitted)
 * @param reversed - whether to traverse in reverse order
 */
export declare function forEach<T>(array: readonly T[], f: (value: T, index: number, halt: () => void) => void, state?: TraverseState, reversed?: boolean): void;
/**
 * Returns a copy of the array where the given function is applied to each element.
 * Supports an index offset useful for composed traversals.
 * @typeparam T - source element type
 * @typeparam R - result element type
 * @param array - the source array
 * @param f - the mapping function
 * @param indexOffset - optional start index value passed to `f`
 */
export declare function map<T, R>(array: readonly T[], f: (value: T, index: number) => R, indexOffset?: number): R[];
/**
 * Returns a copy of the array where the given function is applied to each element in reverse order.
 * @typeparam T - source element type
 * @typeparam R - result element type
 * @param array - the source array
 * @param f - the mapping function
 * @param indexOffset - optional index offset passed to `f`
 */
export declare function reverseMap<T, R>(array: readonly T[], f: (value: T, index: number) => R, indexOffset?: number): R[];
/**
 * Internal helper to prepend a value using `toSpliced`.
 * @internal
 */
export declare function _prependNew<T>(array: readonly T[], value: T): ArrayNonEmpty<T>;
/**
 * Internal helper to prepend a value using legacy cloning.
 * @internal
 */
export declare function _prependOld<T>(array: readonly T[], value: T): ArrayNonEmpty<T>;
/**
 * Returns a copy of the array with the given value inserted at the start.
 * @typeparam T - element type
 * @param array - the source array
 * @param value - value to insert at index 0
 */
export declare const prepend: typeof _prependNew;
/**
 * Internal helper to obtain the last element using modern `at`.
 * @internal
 */
export declare function _lastNew<T>(arr: readonly T[]): T;
/**
 * Internal helper to obtain the last element using index arithmetic.
 * @internal
 */
export declare function _lastOld<T>(arr: readonly T[]): T;
/**
 * Returns the last element of the array.
 * @typeparam T - element type
 * @param arr - the array
 */
export declare const last: typeof _lastNew;
/**
 * Internal helper implementing an immutable index update via `with`.
 * @internal
 */
export declare function _updateNew<T>(arr: readonly T[], index: number, updater: Update<T>): readonly T[];
/**
 * Internal helper implementing an immutable index update via cloning.
 * @internal
 */
export declare function _updateOld<T>(arr: readonly T[], index: number, updater: Update<T>): readonly T[];
/**
 * Returns a copy of the array where the element at the given index is replaced using the provided updater.
 * If the result value is identical (by `Object.is`) the original array is returned.
 * @typeparam T - element type
 * @param arr - the source array
 * @param index - the index to update
 * @param updater - value or function update description
 */
export declare const update: typeof _updateNew;
/**
 * Internal helper applying a modifier function via `with`.
 * @internal
 */
export declare function _modNew<T>(arr: readonly T[], index: number, f: (value: T) => T): readonly T[];
/**
 * Internal helper applying a modifier function via cloning.
 * @internal
 */
export declare function _modOld<T>(arr: readonly T[], index: number, f: (value: T) => T): readonly T[];
/**
 * Returns a copy of the array where the element at the given index is transformed by a modifier function.
 * If the result value is identical (by `Object.is`) the original array is returned.
 * @typeparam T - element type
 * @param arr - the source array
 * @param index - the index to modify
 * @param f - modifier function receiving the current value
 */
export declare const mod: typeof _modNew;
/**
 * Internal helper for inserting a value using `toSpliced`.
 * @internal
 */
export declare function _insertNew<T>(arr: readonly T[], index: number, value: T): T[];
/**
 * Internal helper for inserting a value using legacy `splice` on a clone.
 * @internal
 */
export declare function _insertOld<T>(arr: readonly T[], index: number, value: T): T[];
/**
 * Returns a copy of the array where at the given index the provided value is inserted.
 * @typeparam T - element type
 * @param arr - the source array
 * @param index - insertion index
 * @param value - value to insert
 */
export declare const insert: typeof _insertNew;
/**
 * Returns a copy of the array without its first element.
 * @typeparam T - element type
 * @param arr - the source array
 */
export declare function tail<T>(arr: readonly T[]): T[];
/**
 * Returns a copy of the array without its last element.
 * @typeparam T - element type
 * @param arr - the source array
 */
export declare function init<T>(arr: readonly T[]): T[];
/**
 * Internal helper providing an immutable `splice` using `toSpliced`.
 * @internal
 */
export declare function _spliceNew<T>(arr: readonly T[], start: number, deleteCount: number, ...items: T[]): T[];
/**
 * Internal helper providing an immutable `splice` via cloning.
 * @internal
 */
export declare function _spliceOld<T>(arr: readonly T[], start: number, deleteCount: number, ...items: T[]): T[];
/**
 * Immutable version of the array `.splice` command, always returning a new array.
 * @typeparam T - element type
 * @param arr - the source array
 * @param start - start index
 * @param deleteCount - number of elements to delete
 * @param items - optional items to insert
 */
export declare const splice: typeof _spliceNew;
/**
 * Returns a copy of a (potentially) sparse array preserving sparsity (skips holes).
 * @typeparam T - element type
 * @param arr - the source sparse array
 */
export declare function copySparse<T>(arr: readonly T[]): T[];
/**
 * Returns a copy of a sparse array applying the given function to each present element, preserving holes.
 * @typeparam T - source element type
 * @typeparam T2 - result element type
 * @param arr - the source sparse array
 * @param f - mapping function
 */
export declare function mapSparse<T, T2>(arr: readonly T[], f: (value: T, index: number) => T2): T2[];