heap-typed
Version:
Heap. Javascript & Typescript Data Structure.
405 lines (404 loc) • 17 kB
TypeScript
/**
* data-structure-typed
* @author Kirk Qi
* @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
* @license MIT License
*/
import type { Comparator, DFSOrderPattern, ElementCallback, HeapOptions } from '../../types';
import { IterableElementBase } from '../base';
/**
* 1. Complete Binary Tree: Heaps are typically complete binary trees, meaning every level is fully filled except possibly for the last level, which has nodes as far left as possible.
* 2. Heap Properties: Each node in a heap follows a specific order property, which varies depending on the type of heap:
* Max Heap: The value of each parent node is greater than or equal to the value of its children.
* Min Heap: The value of each parent node is less than or equal to the value of its children.
* 3. Root Node Access: In a heap, the largest element (in a max heap) or the smallest element (in a min heap) is always at the root of the tree.
* 4. Efficient Insertion and Deletion: Due to its structure, a heap allows for insertion and deletion operations in logarithmic time (O(log n)).
* 5. Managing Dynamic Data Sets: Heaps effectively manage dynamic data sets, especially when frequent access to the largest or smallest elements is required.
* 6. Non-linear Search: While a heap allows rapid access to its largest or smallest element, it is less efficient for other operations, such as searching for a specific element, as it is not designed for these tasks.
* 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
* 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prime's minimum-spanning tree algorithm, which use heaps to improve performance.
*/
export declare class Heap<E = any, R = any> extends IterableElementBase<E, R, Heap<E, R>> {
/**
* The constructor initializes a heap data structure with optional elements and options.
* @param elements - The `elements` parameter is an iterable object that contains the initial
* elements to be added to the heap.
* It is an optional parameter, and if not provided, the heap will
* be initialized as empty.
* @param [options] - The `options` parameter is an optional object that can contain additional
* configuration options for the heap.
* In this case, it is used to specify a custom comparator
* function for comparing elements in the heap.
* The comparator function is used to determine the
* order of elements in the heap.
*/
constructor(elements?: Iterable<E> | Iterable<R>, options?: HeapOptions<E, R>);
protected _elements: E[];
/**
* The function returns an array of elements.
* @returns The element array is being returned.
*/
get elements(): E[];
/**
* Get the size (number of elements) of the heap.
*/
get size(): number;
/**
* Get the last element in the heap, which is not necessarily a leaf node.
* @returns The last element or undefined if the heap is empty.
*/
get leaf(): E | undefined;
/**
* Static method that creates a binary heap from an array of elements and a comparison function.
* @returns A new Heap instance.
* @param elements
* @param options
*/
static heapify<E = any, R = any>(elements: Iterable<E>, options: HeapOptions<E, R>): Heap<E>;
/**
* Time Complexity: O(log n)
* Space Complexity: O(1)
*
* Insert an element into the heap and maintain the heap properties.
* @param element - The element to be inserted.
*/
add(element: E): boolean;
/**
* Time Complexity: O(log n)
* Space Complexity: O(1)
*
* Remove and return the top element (the smallest or largest element) from the heap.
* @returns The top element or undefined if the heap is empty.
*/
poll(): E | undefined;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* Peek at the top element of the heap without removing it.
* @returns The top element or undefined if the heap is empty.
*/
peek(): E | undefined;
/**
* Check if the heap is empty.
* @returns True if the heap is empty, otherwise false.
*/
isEmpty(): boolean;
/**
* Reset the elements of the heap. Make the elements empty.
*/
clear(): void;
/**
* Time Complexity: O(n)
* Space Complexity: O(n)
*
* Clear and add elements of the heap
* @param elements
*/
refill(elements: E[]): boolean[];
/**
* Time Complexity: O(n)
* Space Complexity: O(1)
*
* Use a comparison function to check whether a binary heap contains a specific element.
* @param element - the element to check.
* @returns Returns true if the specified element is contained; otherwise, returns false.
*/
has(element: E): boolean;
/**
* Time Complexity: O(n)
* Space Complexity: O(1)
*
* The `delete` function removes an element from an array-like data structure, maintaining the order
* and structure of the remaining elements.
* @param {E} element - The `element` parameter represents the element that you want to delete from
* the array `this.elements`.
* @returns The `delete` function is returning a boolean value. It returns `true` if the element was
* successfully deleted from the array, and `false` if the element was not found in the array.
*/
delete(element: E): boolean;
/**
* Time Complexity: O(n)
* Space Complexity: O(log n)
*
* Depth-first search (DFS) method, different traversal orders can be selected。
* @param order - Traverse order parameter: 'IN' (in-order), 'PRE' (pre-order) or 'POST' (post-order).
* @returns An array containing elements traversed in the specified order.
*/
dfs(order?: DFSOrderPattern): E[];
/**
* Time Complexity: O(n)
* Space Complexity: O(n)
*
* Convert the heap to an array.
* @returns An array containing the elements of the heap.
*/
toArray(): E[];
/**
* Time Complexity: O(n)
* Space Complexity: O(n)
*
* Clone the heap, creating a new heap with the same elements.
* @returns A new Heap instance containing the same elements.
*/
clone(): Heap<E, R>;
/**
* Time Complexity: O(n log n)
* Space Complexity: O(n)
*
* Sort the elements in the heap and return them as an array.
* @returns An array containing the elements sorted in ascending order.
*/
sort(): E[];
/**
* Time Complexity: O(n log n)
* Space Complexity: O(n)
*
* Fix the entire heap to maintain heap properties.
*/
fix(): boolean[];
/**
* Time Complexity: O(n)
* Space Complexity: O(n)
*
* The `filter` function creates a new Heap object containing elements that pass a given callback
* function.
* @param callback - The `callback` parameter is a function that will be called for each element in
* the heap. It takes three arguments: the current element, the index of the current element, and the
* heap itself. The callback function should return a boolean value indicating whether the current
* element should be included in the filtered list
* @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
* to be used as `this` when executing the `callback` function. If `thisArg` is provided, it will be
* passed as the `this` value to the `callback` function. If `thisArg` is
* @returns The `filter` method is returning a new `Heap` object that contains the elements that pass
* the filter condition specified by the `callback` function.
*/
filter(callback: ElementCallback<E, R, boolean, Heap<E, R>>, thisArg?: any): Heap<E, R>;
/**
* Time Complexity: O(n log n)
* Space Complexity: O(n)
*
* The `map` function creates a new heap by applying a callback function to each element of the
* original heap.
* @param callback - The `callback` parameter is a function that will be called for each element in
* the heap. It takes three arguments: `el` (the current element), `index` (the index of the current
* element), and `this` (the heap itself). The callback function should return a value of
* @param comparator - The `comparator` parameter is a function that defines the order of the
* elements in the heap. It takes two elements `a` and `b` as arguments and returns a negative number
* if `a` should be placed before `b`, a positive number if `a` should be placed after
* @param [toElementFn] - The `toElementFn` parameter is an optional function that converts the raw
* element `RR` to the desired type `T`. It takes a single argument `rawElement` of type `RR` and
* returns a value of type `T`. This function is used to transform the elements of the original
* @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
* specify the value of `this` within the callback function. It is used to set the context or scope
* in which the callback function will be executed. If `thisArg` is provided, it will be used as the
* value of
* @returns a new instance of the `Heap` class with the mapped elements.
*/
map<EM, RM>(callback: ElementCallback<E, R, EM, Heap<E, R>>, comparator: Comparator<EM>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): Heap<EM, RM>;
protected _DEFAULT_COMPARATOR: (a: E, b: E) => number;
protected _comparator: Comparator<E>;
/**
* The function returns the value of the _comparator property.
* @returns The `_comparator` property is being returned.
*/
get comparator(): Comparator<E>;
/**
* The function `_getIterator` returns an iterable iterator for the elements in the class.
*/
protected _getIterator(): IterableIterator<E>;
/**
* Time Complexity: O(log n)
* Space Complexity: O(1)
*
* Float operation to maintain heap properties after adding an element.
* @param index - The index of the newly added element.
*/
protected _bubbleUp(index: number): boolean;
/**
* Time Complexity: O(log n)
* Space Complexity: O(1)
*
* Sinking operation to maintain heap properties after removing the top element.
* @param index - The index from which to start sinking.
* @param halfLength
*/
protected _sinkDown(index: number, halfLength: number): boolean;
}
export declare class FibonacciHeapNode<E> {
element: E;
degree: number;
left?: FibonacciHeapNode<E>;
right?: FibonacciHeapNode<E>;
child?: FibonacciHeapNode<E>;
parent?: FibonacciHeapNode<E>;
marked: boolean;
/**
* The constructor function initializes an object with an element and a degree, and sets the marked
* property to false.
* @param {E} element - The "element" parameter represents the value or data that will be stored in
* the node of a data structure. It can be any type of data, such as a number, string, object, or
* even another data structure.
* @param [degree=0] - The degree parameter represents the degree of the element in a data structure
* called a Fibonacci heap. The degree of a node is the number of children it has. By default, the
* degree is set to 0 when a new node is created.
*/
constructor(element: E, degree?: number);
}
export declare class FibonacciHeap<E> {
/**
* The constructor function initializes a FibonacciHeap object with an optional comparator function.
* @param [comparator] - The `comparator` parameter is an optional argument that represents a
* function used to compare elements in the FibonacciHeap. If a comparator function is provided, it
* will be used to determine the order of elements in the heap. If no comparator function is
* provided, a default comparator function will be used.
*/
constructor(comparator?: Comparator<E>);
protected _root?: FibonacciHeapNode<E>;
/**
* The function returns the root node of a Fibonacci heap.
* @returns The method is returning either a FibonacciHeapNode object or undefined.
*/
get root(): FibonacciHeapNode<E> | undefined;
protected _size: number;
/**
* The function returns the size of an object.
* @returns The size of the object, which is a number.
*/
get size(): number;
protected _min?: FibonacciHeapNode<E>;
/**
* The function returns the minimum node in a Fibonacci heap.
* @returns The method is returning the minimum node of the Fibonacci heap, which is of type
* `FibonacciHeapNode<E>`. If there is no minimum node, it will return `undefined`.
*/
get min(): FibonacciHeapNode<E> | undefined;
protected _comparator: Comparator<E>;
/**
* The function returns the comparator used for comparing elements.
* @returns The `_comparator` property of the object.
*/
get comparator(): Comparator<E>;
/**
* Get the size (number of elements) of the heap.
* @returns {number} The size of the heap. Returns 0 if the heap is empty. Returns -1 if the heap is invalid.
*/
clear(): void;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* Insert an element into the heap and maintain the heap properties.
* @param element
* @returns {FibonacciHeap<E>} FibonacciHeap<E> - The heap itself.
*/
add(element: E): FibonacciHeap<E>;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* Insert an element into the heap and maintain the heap properties.
* @param element
* @returns {FibonacciHeap<E>} FibonacciHeap<E> - The heap itself.
*/
push(element: E): FibonacciHeap<E>;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* Peek at the top element of the heap without removing it.
* @returns The top element or undefined if the heap is empty.
* @protected
*/
peek(): E | undefined;
/**
* Time Complexity: O(n), where n is the number of elements in the linked list.
* Space Complexity: O(1)
*
* Get the size (number of elements) of the heap.
* @param {FibonacciHeapNode<E>} head - The head of the linked list.
* @protected
* @returns FibonacciHeapNode<E>[] - An array containing the elements of the linked list.
*/
consumeLinkedList(head?: FibonacciHeapNode<E>): FibonacciHeapNode<E>[];
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* @param parent
* @param node
*/
mergeWithChild(parent: FibonacciHeapNode<E>, node: FibonacciHeapNode<E>): void;
/**
* Time Complexity: O(log n)
* Space Complexity: O(1)
*
* Remove and return the top element (the smallest or largest element) from the heap.
* @returns The top element or undefined if the heap is empty.
*/
poll(): E | undefined;
/**
* Time Complexity: O(log n)
* Space Complexity: O(1)
*
* Remove and return the top element (the smallest or largest element) from the heap.
* @returns The top element or undefined if the heap is empty.
*/
pop(): E | undefined;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* merge two heaps. The heap that is merged will be cleared. The heap that is merged into will remain.
* @param heapToMerge
*/
merge(heapToMerge: FibonacciHeap<E>): void;
/**
* Create a new node.
* @param element
* @protected
*/
createNode(element: E): FibonacciHeapNode<E>;
/**
* Default comparator function used by the heap.
* @param {E} a
* @param {E} b
* @protected
*/
protected _defaultComparator(a: E, b: E): number;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* Merge the given node with the root list.
* @param node - The node to be merged.
*/
protected mergeWithRoot(node: FibonacciHeapNode<E>): void;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* Remove and return the top element (the smallest or largest element) from the heap.
* @param node - The node to be removed.
* @protected
*/
protected removeFromRoot(node: FibonacciHeapNode<E>): void;
/**
* Time Complexity: O(1)
* Space Complexity: O(1)
*
* Remove and return the top element (the smallest or largest element) from the heap.
* @param y
* @param x
* @protected
*/
protected _link(y: FibonacciHeapNode<E>, x: FibonacciHeapNode<E>): void;
/**
* Time Complexity: O(n log n)
* Space Complexity: O(n)
*
* Remove and return the top element (the smallest or largest element) from the heap.
* @protected
*/
protected _consolidate(): void;
}