deque-typed/dist/types/data-structures/binary-tree/tree-map.d.ts

Deque

/**
 * TreeMap (ordered map) — a restricted, native-like API backed by RedBlackTree.
 *
 * Design goals:
 * - No node exposure (no node inputs/outputs)
 * - Native Map-like surface + Java NavigableMap-like helpers
 * - Strict default comparator (number/string/Date), otherwise require comparator
 */
import type { Comparator } from '../../types';
import type { TreeMapEntryCallback, TreeMapOptions, TreeMapRangeOptions, TreeMapReduceCallback } from '../../types';
/**
 * An ordered Map backed by a red-black tree.
 *
 * - Iteration order is ascending by key.
 * - No node exposure: all APIs use keys/values only.
 */
export declare class TreeMap<K = any, V = any, R = [K, V]> implements Iterable<[K, V | undefined]> {
    #private;
    /**
     * Create a TreeMap from an iterable of `[key, value]` entries or raw elements.
     *
     * @param entries - Iterable of `[key, value]` tuples, or raw elements if `toEntryFn` is provided.
     * @param options - Configuration options including optional `toEntryFn` to transform raw elements.
     * @throws {TypeError} If any entry is not a 2-tuple-like value (when no toEntryFn), or when using
     * the default comparator and encountering unsupported/invalid keys (e.g. `NaN`, invalid `Date`).
     * @example
     * // Standard usage with entries
     * const map = new TreeMap([['a', 1], ['b', 2]]);
     *
     * // Using toEntryFn to transform raw objects
     * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
     * const map = new TreeMap<number, User, User>(users, { toEntryFn: u => [u.id, u] });
     */
    constructor(entries?: Iterable<R> | Iterable<[K, V | undefined]>, options?: TreeMapOptions<K, V, R>);
    /**
     * Create the strict default comparator.
     *
     * Supports:
     * - `number` (rejects `NaN`; treats `-0` and `0` as equal)
     * - `string`
     * - `Date` (orders by `getTime()`, rejects invalid dates)
     *
     * For other key types, a custom comparator must be provided.
     */
    static createDefaultComparator<K>(): Comparator<K>;
    private _validateKey;
    /**
     * Number of entries in the map.
     */
    get size(): number;
    /**
     * Whether the map is empty.
     */
    isEmpty(): boolean;
    /**
     * Set or overwrite a value for a key.
     * @remarks Expected time O(log n)
     */
    set(key: K, value: V | undefined): this;
    /**
     * Get the value under a key.
     * @remarks Expected time O(log n)
     */
    get(key: K): V | undefined;
    /**
     * Test whether a key exists.
     * @remarks Expected time O(log n)
     */
    has(key: K): boolean;
    /**
     * Delete a key.
     * @returns `true` if the key existed; otherwise `false`.
     * @remarks Expected time O(log n)
     */
    delete(key: K): boolean;
    /**
     * Remove all entries.
     */
    clear(): void;
    /**
     * Iterate over keys in ascending order.
     */
    keys(): IterableIterator<K>;
    private _entryFromKey;
    /**
     * Iterate over values in ascending key order.
     *
     * Note: values may be `undefined` (TreeMap allows storing `undefined`, like native `Map`).
     */
    values(): IterableIterator<V | undefined>;
    /**
     * Iterate over `[key, value]` entries in ascending key order.
     *
     * Note: values may be `undefined`.
     */
    entries(): IterableIterator<[K, V | undefined]>;
    [Symbol.iterator](): IterableIterator<[K, V | undefined]>;
    /**
     * Visit each entry in ascending key order.
     *
     * Note: callback value may be `undefined`.
     */
    forEach(cb: (value: V | undefined, key: K, map: TreeMap<K, V>) => void, thisArg?: any): void;
    /**
     * Create a new TreeMap by mapping each entry to a new `[key, value]` entry.
     *
     * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
     * @remarks Time O(n log n) expected, Space O(n)
     */
    map<MK, MV>(callbackfn: TreeMapEntryCallback<K, V, [MK, MV], TreeMap<K, V>>, options?: Omit<TreeMapOptions<MK, MV>, 'toEntryFn'> & {
        comparator?: (a: MK, b: MK) => number;
    }, thisArg?: unknown): TreeMap<MK, MV>;
    /**
     * Create a new TreeMap containing only entries that satisfy the predicate.
     * @remarks Time O(n log n) expected, Space O(n)
     */
    filter(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): TreeMap<K, V>;
    /**
     * Reduce entries into a single accumulator.
     * @remarks Time O(n), Space O(1)
     */
    reduce<A>(callbackfn: TreeMapReduceCallback<K, V, A, TreeMap<K, V>>, initialValue: A): A;
    /**
     * Test whether all entries satisfy a predicate.
     * @remarks Time O(n), Space O(1)
     */
    every(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean;
    /**
     * Test whether any entry satisfies a predicate.
     * @remarks Time O(n), Space O(1)
     */
    some(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): boolean;
    /**
     * Find the first entry that satisfies a predicate.
     * @returns The first matching `[key, value]` tuple, or `undefined`.
     * @remarks Time O(n), Space O(1)
     */
    find(callbackfn: TreeMapEntryCallback<K, V, boolean, TreeMap<K, V>>, thisArg?: unknown): [K, V | undefined] | undefined;
    /**
     * Materialize the map into an array of `[key, value]` tuples.
     * @remarks Time O(n), Space O(n)
     */
    toArray(): Array<[K, V | undefined]>;
    /**
     * Print a human-friendly representation.
     * @remarks Time O(n), Space O(n)
     */
    print(): void;
    /**
     * Smallest entry by key.
     */
    first(): [K, V | undefined] | undefined;
    /**
     * Largest entry by key.
     */
    last(): [K, V | undefined] | undefined;
    /**
     * Remove and return the smallest entry.
     */
    pollFirst(): [K, V | undefined] | undefined;
    /**
     * Remove and return the largest entry.
     */
    pollLast(): [K, V | undefined] | undefined;
    /**
     * Smallest entry whose key is >= the given key.
     */
    ceiling(key: K): [K, V | undefined] | undefined;
    /**
     * Largest entry whose key is <= the given key.
     */
    floor(key: K): [K, V | undefined] | undefined;
    /**
     * Smallest entry whose key is > the given key.
     */
    higher(key: K): [K, V | undefined] | undefined;
    /**
     * Largest entry whose key is < the given key.
     */
    lower(key: K): [K, V | undefined] | undefined;
    /**
     * Return all entries in a given key range.
     *
     * @param range `[low, high]`
     * @param options Inclusive/exclusive bounds (defaults to inclusive).
     */
    rangeSearch(range: [K, K], options?: TreeMapRangeOptions): Array<[K, V | undefined]>;
    /**
     * Creates a shallow clone of this map.
     * @remarks Time O(n log n), Space O(n)
     * @example
     * const original = new TreeMap([['a', 1], ['b', 2]]);
     * const copy = original.clone();
     * copy.set('c', 3);
     * original.has('c'); // false (original unchanged)
     */
    clone(): TreeMap<K, V>;
}