min-heap-typed 1.50.1 → 1.50.3

package/src/data-structures/heap/heap.ts

@@ -21,6 +21,16 @@ import { IterableElementBase } from '../base';
  * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prim's minimum spanning tree algorithm, which use heaps to improve performance.
  */
 export class Heap<E = any> extends IterableElementBase<E> {
+  /**
+   * 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> = [], options?: HeapOptions<E>) {
     super();
 
@@ -33,7 +43,6 @@ export class Heap<E = any> extends IterableElementBase<E> {
       for (const el of elements) {
         this.add(el);
       }
-      // this.fix();
     }
   }
 
@@ -45,12 +54,20 @@ export class Heap<E = any> extends IterableElementBase<E> {
     }
   };
 
+  /**
+   * The function returns the value of the _comparator property.
+   * @returns The `_comparator` property is being returned.
+   */
   get comparator() {
     return this._comparator;
   }
 
   protected _elements: E[] = [];
 
+  /**
+   * The function returns an array of elements.
+   * @returns The elements array is being returned.
+   */
   get elements(): E[] {
     return this._elements;
   }
@@ -81,12 +98,13 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
+   * where n is the number of elements in the heap.
    */
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * Insert an element into the heap and maintain the heap properties.
@@ -98,12 +116,13 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
+   * where n is the number of elements in the heap.
    */
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * Remove and return the top element (smallest or largest element) from the heap.
@@ -121,6 +140,14 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * 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.
    */
@@ -144,12 +171,12 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(n), where n is the number of elements in the elements array.
+   * Time Complexity: O(n)
    * Space Complexity: O(n)
    */
 
   /**
-   * Time Complexity: O(n), where n is the number of elements in the elements array.
+   * Time Complexity: O(n)
    * Space Complexity: O(n)
    *
    * Clear and add elements of the heap
@@ -161,12 +188,12 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(n), where n is the number of elements in the heap.
+   * Time Complexity: O(n)
    * Space Complexity: O(1)
    */
 
   /**
-   * Time Complexity: O(n), where n is the number of elements in the heap.
+   * Time Complexity: O(n)
    * Space Complexity: O(1)
    *
    * Use a comparison function to check whether a binary heap contains a specific element.
@@ -178,12 +205,13 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity:  O(n). The worst-case  O(n), where n is the number of elements in the heap. This is because, in the worst case, the element to be deleted is located at the end of the heap (not the root), and after deletion, we may need to reorganize the elements by performing a sinkDown operation.
+   * Time Complexity:  O(n)
    * Space Complexity: O(1)
+   * The worst-case  O(n) This is because, in the worst case, the element to be deleted is located at the end of the heap (not the root), and after deletion, we may need to reorganize the elements by performing a sinkDown operation.
    */
 
   /**
-   * Time Complexity:  O(n). The worst-case  O(n), where n is the number of elements in the heap. This is because, in the worst case, the element to be deleted is located at the end of the heap (not the root), and after deletion, we may need to reorganize the elements by performing a sinkDown operation.
+   * Time Complexity:  O(n)
    * Space Complexity: O(1)
    *
    * The `delete` function removes an element from an array-like data structure, maintaining the order
@@ -209,13 +237,14 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(n), where n is the number of elements in the heap.
-   * Space Complexity: O(h), where h is the height of the heap.
+   * Time Complexity: O(n)
+   * Space Complexity: O(log n)
+   * where log n is the height of the heap.
    */
 
   /**
-   * Time Complexity: O(n), where n is the number of elements in the heap.
-   * Space Complexity: O(h), where h is the height of the heap.
+   * 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).
@@ -307,13 +336,13 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(log n)
-   * Space Complexity: O(1)
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(n)
    */
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(n)
    *
    * Fix the entire heap to maintain heap properties.
    */
@@ -391,6 +420,9 @@ export class Heap<E = any> extends IterableElementBase<E> {
     return mappedHeap;
   }
 
+  /**
+   * The function `_getIterator` returns an iterable iterator for the elements in the class.
+   */
   protected* _getIterator(): IterableIterator<E> {
     for (const element of this.elements) {
       yield element;
@@ -398,7 +430,7 @@ export class Heap<E = any> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(n)
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    */
 
@@ -422,6 +454,11 @@ export class Heap<E = any> extends IterableElementBase<E> {
     return true;
   }
 
+  /**
+   * Time Complexity: O(log n)
+   * Space Complexity: O(1)
+   */
+
   /**
    * Time Complexity: O(log n)
    * Space Complexity: O(1)
@@ -458,6 +495,16 @@ export class 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 = 0) {
     this.element = element;
     this.degree = degree;
@@ -466,6 +513,13 @@ export class FibonacciHeapNode<E> {
 }
 
 export 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>) {
     this.clear();
     this._comparator = comparator || this._defaultComparator;
@@ -477,24 +531,41 @@ export class FibonacciHeap<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 {
     return this._root;
   }
 
   protected _size = 0;
 
+  /**
+   * The function returns the size of an object.
+   * @returns The size of the object, which is a number.
+   */
   get size(): number {
     return this._size;
   }
 
   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 {
     return this._min;
   }
 
   protected _comparator: Comparator<E>;
 
+  /**
+   * The function returns the comparator used for comparing elements.
+   * @returns The `_comparator` property of the object.
+   */
   get comparator(): Comparator<E> {
     return this._comparator;
   }
@@ -623,12 +694,12 @@ export class FibonacciHeap<E> {
   }
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    */
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * Remove and return the top element (smallest or largest element) from the heap.
@@ -639,12 +710,12 @@ export class FibonacciHeap<E> {
   }
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    */
 
   /**
-   * Time Complexity: O(log n), where n is the number of elements in the heap.
+   * Time Complexity: O(log n)
    * Space Complexity: O(1)
    *
    * Remove and return the top element (smallest or largest element) from the heap.
@@ -808,12 +879,12 @@ export class FibonacciHeap<E> {
   }
 
   /**
-   * Time Complexity: O(n log n), where n is the number of elements in the heap.
+   * Time Complexity: O(n log n)
    * Space Complexity: O(n)
    */
 
   /**
-   * Time Complexity: O(n log n), where n is the number of elements in the heap.
+   * Time Complexity: O(n log n)
    * Space Complexity: O(n)
    *
    * Remove and return the top element (smallest or largest element) from the heap.