trie-typed/dist/data-structures/base/linear-base.d.ts

Trie, prefix tree

import type { ElementCallback, LinearBaseOptions, ReduceLinearCallback } from '../../types';
import { IterableElementBase } from './iterable-element-base';
/**
 * Singly-linked list node.
 * @template E - Element type.
 * @remarks Time O(1), Space O(1)
 */
export declare class LinkedListNode<E = any> {
    /**
     * Initialize a node.
     * @param value - Element value.
     * @remarks Time O(1), Space O(1)
     */
    constructor(value: E);
    protected _value: E;
    /**
     * Element payload getter.
     * @returns Element value.
     * @remarks Time O(1), Space O(1)
     */
    get value(): E;
    /**
     * Element payload setter.
     * @param value - New value.
     * @remarks Time O(1), Space O(1)
     */
    set value(value: E);
    protected _next: LinkedListNode<E> | undefined;
    /**
     * Next node getter.
     * @returns Next node or `undefined`.
     * @remarks Time O(1), Space O(1)
     */
    get next(): LinkedListNode<E> | undefined;
    /**
     * Next node setter.
     * @param value - Next node or `undefined`.
     * @remarks Time O(1), Space O(1)
     */
    set next(value: LinkedListNode<E> | undefined);
}
/**
 * Abstract linear container with array-like utilities.
 * @template E - Element type.
 * @template R - Return type for mapped/derived views.
 * @template NODE - Linked node type used by some implementations.
 * @remarks Time O(1), Space O(1)
 */
export declare abstract class LinearBase<E, R = any, NODE extends LinkedListNode<E> = LinkedListNode<E>> extends IterableElementBase<E, R> {
    /**
     * Construct a linear container with runtime options.
     * @param options - `{ maxLen?, ... }` bounds/behavior options.
     * @remarks Time O(1), Space O(1)
     */
    protected constructor(options?: LinearBaseOptions<E, R>);
    /**
     * Element count.
     * @returns Number of elements.
     * @remarks Time O(1), Space O(1)
     */
    abstract get length(): number;
    protected _maxLen: number;
    /**
     * Upper bound for length (if positive), or `-1` when unbounded.
     * @returns Maximum allowed length.
     * @remarks Time O(1), Space O(1)
     */
    get maxLen(): number;
    /**
     * First index of a value from the left.
     * @param searchElement - Value to match.
     * @param fromIndex - Start position (supports negative index).
     * @returns Index or `-1` if not found.
     * @remarks Time O(n), Space O(1)
     */
    indexOf(searchElement: E, fromIndex?: number): number;
    /**
     * Last index of a value from the right.
     * @param searchElement - Value to match.
     * @param fromIndex - Start position (supports negative index).
     * @returns Index or `-1` if not found.
     * @remarks Time O(n), Space O(1)
     */
    lastIndexOf(searchElement: E, fromIndex?: number): number;
    /**
     * Find the first index matching a predicate.
     * @param predicate - `(element, index, self) => boolean`.
     * @param thisArg - Optional `this` for callback.
     * @returns Index or `-1`.
     * @remarks Time O(n), Space O(1)
     */
    findIndex(predicate: ElementCallback<E, R, boolean>, thisArg?: any): number;
    /**
     * Concatenate multiple containers of the same species.
     * @param items - Other lists to append.
     * @returns New container with combined elements (`this` type).
     * @remarks Time O(sum(length)), Space O(sum(length))
     */
    concat(...items: this[]): this;
    /**
     * In-place stable order via array sort semantics.
     * @param compareFn - Comparator `(a, b) => number`.
     * @returns This container.
     * @remarks Time O(n log n), Space O(n) (materializes to array temporarily)
     */
    sort(compareFn?: (a: E, b: E) => number): this;
    /**
     * Remove and/or insert elements at a position (array-compatible).
     * @param start - Start index (supports negative index).
     * @param deleteCount - How many to remove.
     * @param items - Elements to insert.
     * @returns Removed elements as a new list (`this` type).
     * @remarks Time O(n + m), Space O(min(n, m)) where `m = items.length`
     */
    splice(start: number, deleteCount?: number, ...items: E[]): this;
    /**
     * Join all elements into a string.
     * @param separator - Separator string.
     * @returns Concatenated string.
     * @remarks Time O(n), Space O(n)
     */
    join(separator?: string): string;
    /**
     * Snapshot elements into a reversed array.
     * @returns New reversed array.
     * @remarks Time O(n), Space O(n)
     */
    toReversedArray(): E[];
    reduceRight(callbackfn: ReduceLinearCallback<E>): E;
    reduceRight(callbackfn: ReduceLinearCallback<E>, initialValue: E): E;
    /**
     * Right-to-left reduction over elements.
     * @param callbackfn - `(acc, element, index, self) => acc`.
     * @param initialValue - Initial accumulator (optional generic overloads supported).
     * @returns Final accumulator.
     * @remarks Time O(n), Space O(1)
     */
    reduceRight<U>(callbackfn: ReduceLinearCallback<E, U>, initialValue: U): U;
    /**
     * Create a shallow copy of a subrange.
     * @param start - Inclusive start (supports negative index).
     * @param end - Exclusive end (supports negative index).
     * @returns New list with the range (`this` type).
     * @remarks Time O(n), Space O(n)
     */
    slice(start?: number, end?: number): this;
    /**
     * Fill a range with a value.
     * @param value - Value to set.
     * @param start - Inclusive start.
     * @param end - Exclusive end.
     * @returns This list.
     * @remarks Time O(n), Space O(1)
     */
    fill(value: E, start?: number, end?: number): this;
    /**
     * Set the value at an index.
     * @param index - Position (0-based).
     * @param value - New value.
     * @returns `true` if updated.
     * @remarks Time O(1) typical, Space O(1)
     */
    abstract setAt(index: number, value: E): boolean;
    /**
     * Deep clone while preserving concrete subtype.
     * @returns New list of the same species (`this` type).
     * @remarks Time O(n), Space O(n)
     */
    abstract clone(): this;
    /**
     * Reverse the order of elements in-place (or equivalent).
     * @returns This list.
     * @remarks Time O(n), Space O(1)
     */
    abstract reverse(): this;
    /**
     * Append one element or node to the tail.
     * @param elementOrNode - Element or node.
     * @returns `true` if appended.
     * @remarks Time O(1) amortized typical, Space O(1)
     */
    abstract push(elementOrNode: E | NODE): boolean;
    /**
     * Append many elements/nodes at once.
     * @param elements - Iterable of elements or nodes.
     * @returns Array of booleans indicating append success.
     * @remarks Time O(n), Space O(1)
     */
    abstract pushMany(elements: Iterable<E> | Iterable<R> | Iterable<NODE>): boolean[];
    /**
     * Remove one element or node if present.
     * @param elementOrNode - Element or node to delete.
     * @returns `true` if removed.
     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
     */
    abstract delete(elementOrNode: E | NODE | undefined): boolean;
    /**
     * Get element at an index.
     * @param index - Position (0-based).
     * @returns Element or `undefined`.
     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
     */
    abstract at(index: number): E | undefined;
    /**
     * Remove element at a position.
     * @param pos - Position (0-based).
     * @returns Removed element or `undefined`.
     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
     */
    abstract deleteAt(pos: number): E | undefined;
    /**
     * Insert an element/node at a position.
     * @param index - Position (0-based).
     * @param newElementOrNode - Element or node to insert.
     * @returns `true` if inserted.
     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
     */
    abstract addAt(index: number, newElementOrNode: E | NODE): boolean;
    /**
     * Create an empty list of the same species.
     * @param options - Runtime options to carry.
     * @returns Empty list (`this` type).
     * @remarks Time O(1), Space O(1)
     */
    protected abstract _createInstance(options?: LinearBaseOptions<E, R>): this;
    /**
     * Reverse-direction iterator over elements.
     * @returns Iterator of elements from tail to head.
     * @remarks Time O(n), Space O(1)
     */
    protected abstract _getReverseIterator(...args: any[]): IterableIterator<E>;
}
/**
 * Linked-list specialized linear container.
 * @template E - Element type.
 * @template R - Return type for mapped/derived views.
 * @template NODE - Linked node type.
 * @remarks Time O(1), Space O(1)
 */
export declare abstract class LinearLinkedBase<E, R = any, NODE extends LinkedListNode<E> = LinkedListNode<E>> extends LinearBase<E, R, NODE> {
    protected constructor(options?: LinearBaseOptions<E, R>);
    /**
     * Linked-list optimized `indexOf` (forwards scan).
     * @param searchElement - Value to match.
     * @param fromIndex - Start position.
     * @returns Index or `-1`.
     * @remarks Time O(n), Space O(1)
     */
    indexOf(searchElement: E, fromIndex?: number): number;
    /**
     * Linked-list optimized `lastIndexOf` (reverse scan).
     * @param searchElement - Value to match.
     * @param fromIndex - Start position.
     * @returns Index or `-1`.
     * @remarks Time O(n), Space O(1)
     */
    lastIndexOf(searchElement: E, fromIndex?: number): number;
    /**
     * Concatenate lists/elements preserving order.
     * @param items - Elements or `LinearBase` instances.
     * @returns New list with combined elements (`this` type).
     * @remarks Time O(sum(length)), Space O(sum(length))
     */
    concat(...items: LinearBase<E, R>[]): this;
    /**
     * Slice via forward iteration (no random access required).
     * @param start - Inclusive start (supports negative index).
     * @param end - Exclusive end (supports negative index).
     * @returns New list (`this` type).
     * @remarks Time O(n), Space O(n)
     */
    slice(start?: number, end?: number): this;
    /**
     * Splice by walking node iterators from the start index.
     * @param start - Start index.
     * @param deleteCount - How many elements to remove.
     * @param items - Elements to insert after the splice point.
     * @returns Removed elements as a new list (`this` type).
     * @remarks Time O(n + m), Space O(min(n, m)) where `m = items.length`
     */
    splice(start: number, deleteCount?: number, ...items: E[]): this;
    reduceRight(callbackfn: ReduceLinearCallback<E>): E;
    reduceRight(callbackfn: ReduceLinearCallback<E>, initialValue: E): E;
    /**
     * Right-to-left reduction using reverse iterator.
     * @param callbackfn - `(acc, element, index, self) => acc`.
     * @param initialValue - Initial accumulator.
     * @returns Final accumulator.
     * @remarks Time O(n), Space O(1)
     */
    reduceRight<U>(callbackfn: ReduceLinearCallback<E, U>, initialValue: U): U;
    /**
     * Delete by element or node in a linked list.
     * @param elementOrNode - Element or node.
     * @returns `true` if removed.
     * @remarks Time O(1)~O(n) depending on availability of links, Space O(1)
     */
    abstract delete(elementOrNode: E | NODE | undefined): boolean;
    /**
     * Insert new element/node before an existing node.
     * @param existingElementOrNode - Reference element/node.
     * @param newElementOrNode - Element/node to insert.
     * @returns `true` if inserted.
     * @remarks Time O(1)~O(n) depending on reference access, Space O(1)
     */
    abstract addBefore(existingElementOrNode: E | NODE, newElementOrNode: E | NODE): boolean;
    /**
     * Insert new element/node after an existing node.
     * @param existingElementOrNode - Reference element/node.
     * @param newElementOrNode - Element/node to insert.
     * @returns `true` if inserted.
     * @remarks Time O(1)~O(n) depending on reference access, Space O(1)
     */
    abstract addAfter(existingElementOrNode: E | NODE, newElementOrNode: E | NODE): boolean;
    /**
     * Node at index (for random-access emulation).
     * @param index - Position (0-based).
     * @returns Node or `undefined`.
     * @remarks Time O(n), Space O(1)
     */
    abstract getNodeAt(index: number): NODE | undefined;
    /**
     * Iterate linked nodes from head to tail.
     * @returns Iterator over nodes.
     * @remarks Time O(n), Space O(1)
     */
    protected abstract _getNodeIterator(...args: any[]): IterableIterator<NODE>;
    /**
     * Get previous node of a given node.
     * @param node - Current node.
     * @returns Previous node or `undefined`.
     * @remarks Time O(1)~O(n) depending on list variant (singly vs doubly), Space O(1)
     */
    protected abstract _getPrevNode(node: NODE): NODE | undefined;
}