tree-multimap-typed/dist/data-structures/queue/deque.d.ts

Tree Multimap

/**
 * data-structure-typed
 *
 * @author Pablo Zeng
 * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
 * @license MIT License
 */
import type { DequeOptions, ElementCallback, IterableElementBaseOptions, IterableWithSizeOrLength, LinearBaseOptions } from '../../types';
import { LinearBase } from '../base/linear-base';
/**
 * Deque implemented with circular buckets allowing O(1) amortized push/pop at both ends.
 * @remarks Time O(1), Space O(1)
 * @template E
 * @template R
 * 1. Operations at Both Ends: Supports adding and removing elements at both the front and back of the queue. This allows it to be used as a stack (last in, first out) and a queue (first in, first out).
 * 2. Efficient Random Access: Being based on an array, it offers fast random access capability, allowing constant time access to any element.
 * 3. Continuous Memory Allocation: Since it is based on an array, all elements are stored contiguously in memory, which can bring cache friendliness and efficient memory access.
 * 4. Efficiency: Adding and removing elements at both ends of a deque is usually very fast. However, when the dynamic array needs to expand, it may involve copying the entire array to a larger one, and this operation has a time complexity of O(n).
 * 5. Performance jitter: Deque may experience performance jitter, but DoublyLinkedList will not
 * @example
 * // prize roulette
 *     class PrizeRoulette {
 *       private deque: Deque<string>;
 *
 *       constructor(prizes: string[]) {
 *         // Initialize the deque with prizes
 *         this.deque = new Deque<string>(prizes);
 *       }
 *
 *       // Rotate clockwise to the right (forward)
 *       rotateClockwise(steps: number): void {
 *         const n = this.deque.length;
 *         if (n === 0) return;
 *
 *         for (let i = 0; i < steps; i++) {
 *           const last = this.deque.pop(); // Remove the last element
 *           this.deque.unshift(last!); // Add it to the front
 *         }
 *       }
 *
 *       // Rotate counterclockwise to the left (backward)
 *       rotateCounterClockwise(steps: number): void {
 *         const n = this.deque.length;
 *         if (n === 0) return;
 *
 *         for (let i = 0; i < steps; i++) {
 *           const first = this.deque.shift(); // Remove the first element
 *           this.deque.push(first!); // Add it to the back
 *         }
 *       }
 *
 *       // Display the current prize at the head
 *       display() {
 *         return this.deque.first;
 *       }
 *     }
 *
 *     // Example usage
 *     const prizes = ['Car', 'Bike', 'Laptop', 'Phone', 'Watch', 'Headphones']; // Initialize the prize list
 *     const roulette = new PrizeRoulette(prizes);
 *
 *     // Display the initial state
 *     console.log(roulette.display()); // 'Car' // Car
 *
 *     // Rotate clockwise by 3 steps
 *     roulette.rotateClockwise(3);
 *     console.log(roulette.display()); // 'Phone' // Phone
 *
 *     // Rotate counterclockwise by 2 steps
 *     roulette.rotateCounterClockwise(2);
 *     console.log(roulette.display()); // 'Headphones'
 * @example
 * // sliding window
 *     // Maximum function of sliding window
 *     function maxSlidingWindow(nums: number[], k: number): number[] {
 *       const n = nums.length;
 *       if (n * k === 0) return [];
 *
 *       const deq = new Deque<number>();
 *       const result: number[] = [];
 *
 *       for (let i = 0; i < n; i++) {
 *         // Delete indexes in the queue that are not within the window range
 *         if (deq.length > 0 && deq.first! === i - k) {
 *           deq.shift();
 *         }
 *
 *         // Remove all indices less than the current value from the tail of the queue
 *         while (deq.length > 0 && nums[deq.last!] < nums[i]) {
 *           deq.pop();
 *         }
 *
 *         // Add the current index to the end of the queue
 *         deq.push(i);
 *
 *         // Add the maximum value of the window to the results
 *         if (i >= k - 1) {
 *           result.push(nums[deq.first!]);
 *         }
 *       }
 *
 *       return result;
 *     }
 *
 *     const nums = [1, 3, -1, -3, 5, 3, 6, 7];
 *     const k = 3;
 *     console.log(maxSlidingWindow(nums, k)); // [3, 3, 5, 5, 6, 7]
 */
export declare class Deque<E = any, R = any> extends LinearBase<E, R> {
    protected _equals: (a: E, b: E) => boolean;
    /**
     * Create a Deque and optionally bulk-insert elements.
     * @remarks Time O(N), Space O(N)
     * @param [elements] - Iterable (or iterable-like) of elements/records to insert.
     * @param [options] - Options such as bucketSize, toElementFn, and maxLen.
     * @returns New Deque instance.
     */
    constructor(elements?: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>, options?: DequeOptions<E, R>);
    protected _bucketSize: number;
    /**
     * Get the current bucket size.
     * @remarks Time O(1), Space O(1)
     * @returns Bucket capacity per bucket.
     */
    get bucketSize(): number;
    protected _bucketFirst: number;
    /**
     * Get the index of the first bucket in use.
     * @remarks Time O(1), Space O(1)
     * @returns Zero-based bucket index.
     */
    get bucketFirst(): number;
    protected _firstInBucket: number;
    /**
     * Get the index inside the first bucket.
     * @remarks Time O(1), Space O(1)
     * @returns Zero-based index within the first bucket.
     */
    get firstInBucket(): number;
    protected _bucketLast: number;
    /**
     * Get the index of the last bucket in use.
     * @remarks Time O(1), Space O(1)
     * @returns Zero-based bucket index.
     */
    get bucketLast(): number;
    protected _lastInBucket: number;
    /**
     * Get the index inside the last bucket.
     * @remarks Time O(1), Space O(1)
     * @returns Zero-based index within the last bucket.
     */
    get lastInBucket(): number;
    protected _bucketCount: number;
    /**
     * Get the number of buckets allocated.
     * @remarks Time O(1), Space O(1)
     * @returns Bucket count.
     */
    get bucketCount(): number;
    protected _buckets: E[][];
    /**
     * Get the internal buckets array.
     * @remarks Time O(1), Space O(1)
     * @returns Array of buckets storing values.
     */
    get buckets(): E[][];
    protected _length: number;
    /**
     * Get the number of elements in the deque.
     * @remarks Time O(1), Space O(1)
     * @returns Current length.
     */
    get length(): number;
    /**
     * Get the first element without removing it.
     * @remarks Time O(1), Space O(1)
     * @returns First element or undefined.
     */
    get first(): E | undefined;
    /**
     * Get the last element without removing it.
     * @remarks Time O(1), Space O(1)
     * @returns Last element or undefined.
     */
    get last(): E | undefined;
    /**
     * Create a Deque from an array of elements.
     * @remarks Time O(N), Space O(N)
     * @template E
     * @template R
     * @param this - Constructor (subclass) to instantiate.
     * @param data - Array of elements to insert in order.
     * @param [options] - Options forwarded to the constructor.
     * @returns A new Deque populated from the array.
     */
    static fromArray<E, R = any>(this: new (elements?: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>, options?: DequeOptions<E, R>) => any, data: E[], options?: DequeOptions<E, R>): any;
    /**
     * Append one element at the back.
     * @remarks Time O(1) amortized, Space O(1)
     * @param element - Element to append.
     * @returns True when appended.
     */
    push(element: E): boolean;
    /**
     * Remove and return the last element.
     * @remarks Time O(1), Space O(1)
     * @returns Removed element or undefined.
     */
    pop(): E | undefined;
    /**
     * Remove and return the first element.
     * @remarks Time O(1) amortized, Space O(1)
     * @returns Removed element or undefined.
     */
    shift(): E | undefined;
    /**
     * Prepend one element at the front.
     * @remarks Time O(1) amortized, Space O(1)
     * @param element - Element to prepend.
     * @returns True when prepended.
     */
    unshift(element: E): boolean;
    /**
     * Append a sequence of elements.
     * @remarks Time O(N), Space O(1)
     * @param elements - Iterable (or iterable-like) of elements/records.
     * @returns Array of per-element success flags.
     */
    pushMany(elements: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>): boolean[];
    /**
     * Prepend a sequence of elements.
     * @remarks Time O(N), Space O(1)
     * @param [elements] - Iterable (or iterable-like) of elements/records.
     * @returns Array of per-element success flags.
     */
    unshiftMany(elements?: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>): boolean[];
    /**
     * Check whether the deque is empty.
     * @remarks Time O(1), Space O(1)
     * @returns True if length is 0.
     */
    isEmpty(): boolean;
    /**
     * Remove all elements and reset structure.
     * @remarks Time O(1), Space O(1)
     * @returns void
     */
    clear(): void;
    /**
     * Get the element at a given position.
     * @remarks Time O(1), Space O(1)
     * @param pos - Zero-based position from the front.
     * @returns Element or undefined.
     */
    at(pos: number): E | undefined;
    /**
     * Replace the element at a given position.
     * @remarks Time O(1), Space O(1)
     * @param pos - Zero-based position from the front.
     * @param element - New element value.
     * @returns True if updated.
     */
    setAt(pos: number, element: E): boolean;
    /**
     * Insert repeated copies of an element at a position.
     * @remarks Time O(N), Space O(1)
     * @param pos - Zero-based position from the front.
     * @param element - Element to insert.
     * @param [num] - Number of times to insert (default 1).
     * @returns True if inserted.
     */
    addAt(pos: number, element: E, num?: number): boolean;
    /**
     * Cut the deque to keep items up to index; optionally mutate in-place.
     * @remarks Time O(N), Space O(1)
     * @param pos - Last index to keep.
     * @param [isCutSelf] - When true, mutate this deque; otherwise return a new deque.
     * @returns This deque if in-place; otherwise a new deque of the prefix.
     */
    cut(pos: number, isCutSelf?: boolean): Deque<E>;
    /**
     * Remove and/or insert elements at a position (array-like behavior).
     * @remarks Time O(N + M), Space O(M)
     * @param start - Start index (clamped to [0, length]).
     * @param [deleteCount] - Number of elements to remove (default: length - start).
     * @param [items] - Elements to insert after `start`.
     * @returns A new deque containing the removed elements (typed as `this`).
     */
    splice(start: number, deleteCount?: number, ...items: E[]): this;
    /**
     * Cut the deque to keep items from index onward; optionally mutate in-place.
     * @remarks Time O(N), Space O(1)
     * @param pos - First index to keep.
     * @param [isCutSelf] - When true, mutate this deque; otherwise return a new deque.
     * @returns This deque if in-place; otherwise a new deque of the suffix.
     */
    cutRest(pos: number, isCutSelf?: boolean): Deque<E>;
    /**
     * Delete the element at a given position.
     * @remarks Time O(N), Space O(1)
     * @param pos - Zero-based position from the front.
     * @returns Removed element or undefined.
     */
    deleteAt(pos: number): E | undefined;
    /**
     * Delete the first occurrence of a value.
     * @remarks Time O(N), Space O(1)
     * @param element - Element to remove (using the configured equality).
     * @returns True if an element was removed.
     */
    delete(element: E): boolean;
    /**
     * Delete the first element matching a predicate.
     * @remarks Time O(N), Space O(1)
     * @param predicate - Function (value, index, deque) → boolean.
     * @returns True if a match was removed.
     */
    deleteWhere(predicate: (value: E, index: number, deque: this) => boolean): boolean;
    /**
     * Set the equality comparator used by delete operations.
     * @remarks Time O(1), Space O(1)
     * @param equals - Equality predicate (a, b) → boolean.
     * @returns This deque.
     */
    setEquality(equals: (a: E, b: E) => boolean): this;
    /**
     * Reverse the deque by reversing buckets and pointers.
     * @remarks Time O(N), Space O(N)
     * @returns This deque.
     */
    reverse(): this;
    /**
     * Deduplicate consecutive equal elements in-place.
     * @remarks Time O(N), Space O(1)
     * @returns This deque.
     */
    unique(): this;
    /**
     * Trim unused buckets to fit exactly the active range.
     * @remarks Time O(N), Space O(1)
     * @returns void
     */
    shrinkToFit(): void;
    /**
     * Deep clone this deque, preserving options.
     * @remarks Time O(N), Space O(N)
     * @returns A new deque with the same content and options.
     */
    clone(): this;
    /**
     * Filter elements into a new deque of the same class.
     * @remarks Time O(N), Space O(N)
     * @param predicate - Predicate (value, index, deque) → boolean to keep element.
     * @param [thisArg] - Value for `this` inside the predicate.
     * @returns A new deque with kept elements.
     */
    filter(predicate: ElementCallback<E, R, boolean>, thisArg?: any): this;
    /**
     * Map elements into a new deque of the same element type.
     * @remarks Time O(N), Space O(N)
     * @param callback - Mapping function (value, index, deque) → newValue.
     * @param [thisArg] - Value for `this` inside the callback.
     * @returns A new deque with mapped values.
     */
    mapSame(callback: ElementCallback<E, R, E>, thisArg?: any): this;
    /**
     * Map elements into a new deque (possibly different element type).
     * @remarks Time O(N), Space O(N)
     * @template EM
     * @template RM
     * @param callback - Mapping function (value, index, deque) → newElement.
     * @param [options] - Options for the output deque (e.g., bucketSize, toElementFn, maxLen).
     * @param [thisArg] - Value for `this` inside the callback.
     * @returns A new Deque with mapped elements.
     */
    map<EM, RM>(callback: ElementCallback<E, R, EM>, options?: IterableElementBaseOptions<EM, RM>, thisArg?: any): Deque<EM, RM>;
    /**
     * (Protected) Set the internal bucket size.
     * @remarks Time O(1), Space O(1)
     * @param size - Bucket capacity to assign.
     * @returns void
     */
    protected _setBucketSize(size: number): void;
    /**
     * (Protected) Iterate elements from front to back.
     * @remarks Time O(N), Space O(1)
     * @returns Iterator of elements.
     */
    protected _getIterator(): IterableIterator<E>;
    /**
     * (Protected) Reallocate buckets to make room near the ends.
     * @remarks Time O(N), Space O(N)
     * @param [needBucketNum] - How many extra buckets to add; defaults to half of current.
     * @returns void
     */
    protected _reallocate(needBucketNum?: number): void;
    /**
     * (Protected) Translate a logical position to bucket/offset.
     * @remarks Time O(1), Space O(1)
     * @param pos - Zero-based position.
     * @returns An object containing bucketIndex and indexInBucket.
     */
    protected _getBucketAndPosition(pos: number): {
        bucketIndex: number;
        indexInBucket: number;
    };
    /**
     * (Protected) Create an empty instance of the same concrete class.
     * @remarks Time O(1), Space O(1)
     * @param [options] - Options forwarded to the constructor.
     * @returns An empty like-kind deque instance.
     */
    protected _createInstance(options?: LinearBaseOptions<E, R>): this;
    /**
     * (Protected) Create a like-kind deque seeded by elements.
     * @remarks Time O(N), Space O(N)
     * @template T
     * @template RR
     * @param [elements] - Iterable used to seed the new deque.
     * @param [options] - Options forwarded to the constructor.
     * @returns A like-kind Deque instance.
     */
    protected _createLike<T = E, RR = R>(elements?: IterableWithSizeOrLength<T> | IterableWithSizeOrLength<RR>, options?: DequeOptions<T, RR>): any;
    /**
     * (Protected) Iterate elements from back to front.
     * @remarks Time O(N), Space O(1)
     * @returns Iterator of elements.
     */
    protected _getReverseIterator(): IterableIterator<E>;
}