data-structure-typed 1.45.3 → 1.46.0

package/dist/mjs/data-structures/heap/heap.js

@@ -7,14 +7,14 @@
 export class Heap {
     constructor(options) {
         this._comparator = options.comparator;
-        if (options.nodes && options.nodes.length > 0) {
-            this._nodes = options.nodes;
+        if (options.elements && options.elements.length > 0) {
+            this._elements = options.elements;
             this.fix();
         }
     }
-    _nodes = [];
-    get nodes() {
-        return this._nodes;
+    _elements = [];
+    get elements() {
+        return this._elements;
     }
     _comparator;
     get comparator() {
@@ -24,17 +24,17 @@ export class Heap {
      * Get the size (number of elements) of the heap.
      */
     get size() {
-        return this.nodes.length;
+        return this.elements.length;
     }
     /**
      * 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() {
-        return this.nodes[this.size - 1] ?? undefined;
+        return this.elements[this.size - 1] ?? undefined;
     }
     /**
-     * Static method that creates a binary heap from an array of nodes and a comparison function.
+     * Static method that creates a binary heap from an array of elements and a comparison function.
      * @returns A new Heap instance.
      * @param options
      */
@@ -42,11 +42,11 @@ export class Heap {
         return new Heap(options);
     }
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      *
      * Insert an element into the heap and maintain the heap properties.
@@ -56,50 +56,49 @@ export class Heap {
         return this.push(element);
     }
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      *
      * Insert an element into the heap and maintain the heap properties.
      * @param element - The element to be inserted.
      */
     push(element) {
-        this.nodes.push(element);
-        this.bubbleUp(this.nodes.length - 1);
+        this._elements.push(element);
+        this._bubbleUp(this.elements.length - 1);
         return this;
     }
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      *
      * Remove and return the top element (smallest or largest element) from the heap.
      * @returns The top element or undefined if the heap is empty.
      */
     poll() {
-        if (this.nodes.length === 0) {
-            return undefined;
-        }
-        if (this.nodes.length === 1) {
-            return this.nodes.pop();
+        if (this.elements.length === 0)
+            return;
+        const value = this.elements[0];
+        const last = this.elements.pop();
+        if (this.elements.length) {
+            this.elements[0] = last;
+            this._sinkDown(0, this.elements.length >> 1);
         }
-        const topValue = this.nodes[0];
-        this.nodes[0] = this.nodes.pop();
-        this.sinkDown(0);
-        return topValue;
+        return value;
     }
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      *
      * Remove and return the top element (smallest or largest element) from the heap.
@@ -113,10 +112,7 @@ export class Heap {
      * @returns The top element or undefined if the heap is empty.
      */
     peek() {
-        if (this.nodes.length === 0) {
-            return undefined;
-        }
-        return this.nodes[0];
+        return this.elements[0];
     }
     /**
      * Check if the heap is empty.
@@ -126,32 +122,32 @@ export class Heap {
         return this.size === 0;
     }
     /**
-     * Reset the nodes of the heap. Make the nodes empty.
+     * Reset the elements of the heap. Make the elements empty.
      */
     clear() {
-        this._nodes = [];
+        this._elements = [];
     }
     /**
-     * Time Complexity: O(n), where n is the number of elements in the nodes array.
+     * Time Complexity: O(n), where n is the number of elements in the elements array.
      * Space Complexity: O(n)
      */
     /**
-     * Time Complexity: O(n), where n is the number of elements in the nodes array.
+     * Time Complexity: O(n), where n is the number of elements in the elements array.
      * Space Complexity: O(n)
      *
-     * Clear and add nodes of the heap
-     * @param nodes
+     * Clear and add elements of the heap
+     * @param elements
      */
-    refill(nodes) {
-        this._nodes = nodes;
+    refill(elements) {
+        this._elements = elements;
         this.fix();
     }
     /**
-     * Time Complexity: O(n), where n is the number of nodes in the heap.
+     * Time Complexity: O(n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(n), where n is the number of nodes in the heap.
+     * Time Complexity: O(n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      *
      * Use a comparison function to check whether a binary heap contains a specific element.
@@ -159,14 +155,46 @@ export class Heap {
      * @returns Returns true if the specified element is contained; otherwise, returns false.
      */
     has(element) {
-        return this.nodes.includes(element);
+        return this.elements.includes(element);
     }
     /**
-     * Time Complexity: O(n), where n is the number of nodes in the heap.
+     * 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.
+     * Space Complexity: O(1)
+     */
+    /**
+     * 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.
+     * 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) {
+        const index = this.elements.indexOf(element);
+        if (index < 0)
+            return false;
+        if (index === 0) {
+            this.pop();
+        }
+        else if (index === this.elements.length - 1) {
+            this.elements.pop();
+        }
+        else {
+            this.elements.splice(index, 1, this.elements.pop());
+            this._bubbleUp(index);
+            this._sinkDown(index, this.elements.length >> 1);
+        }
+        return true;
+    }
+    /**
+     * 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), where n is the number of nodes in 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.
      *
      * Depth-first search (DFS) method, different traversal orders can be selected。
@@ -180,18 +208,18 @@ export class Heap {
             if (index < this.size) {
                 if (order === 'in') {
                     dfsHelper(2 * index + 1);
-                    result.push(this.nodes[index]);
+                    result.push(this.elements[index]);
                     dfsHelper(2 * index + 2);
                 }
                 else if (order === 'pre') {
-                    result.push(this.nodes[index]);
+                    result.push(this.elements[index]);
                     dfsHelper(2 * index + 1);
                     dfsHelper(2 * index + 2);
                 }
                 else if (order === 'post') {
                     dfsHelper(2 * index + 1);
                     dfsHelper(2 * index + 2);
-                    result.push(this.nodes[index]);
+                    result.push(this.elements[index]);
                 }
             }
         };
@@ -210,14 +238,7 @@ export class Heap {
      * @returns An array containing the elements of the heap.
      */
     toArray() {
-        return [...this.nodes];
-    }
-    /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     */
-    getNodes() {
-        return this.nodes;
+        return [...this.elements];
     }
     /**
      * Time Complexity: O(n)
@@ -232,7 +253,7 @@ export class Heap {
      */
     clone() {
         const clonedHeap = new Heap({ comparator: this.comparator });
-        clonedHeap._nodes = [...this.nodes];
+        clonedHeap._elements = [...this.elements];
         return clonedHeap;
     }
     /**
@@ -261,35 +282,14 @@ export class Heap {
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n)
+     * Time Complexity: O(n)
      * Space Complexity: O(1)
      *
-     * Float operation to maintain heap properties after adding an element.
-     * @param index - The index of the newly added element.
+     * Fix the entire heap to maintain heap properties.
      */
-    bubbleUp(index) {
-        // const element = this.nodes[index];
-        // while (index > 0) {
-        //   const parentIndex = (index - 1) >> 1;
-        //   const parent = this.nodes[parentIndex];
-        //   if (this.comparator(element, parent) < 0) {
-        //     this.nodes[index] = parent;
-        //     this.nodes[parentIndex] = element;
-        //     index = parentIndex;
-        //   } else {
-        //     break;
-        //   }
-        // }
-        const item = this.nodes[index];
-        while (index > 0) {
-            const parent = (index - 1) >> 1;
-            const parentItem = this.nodes[parent];
-            if (this.comparator(parentItem, item) <= 0)
-                break;
-            this.nodes[index] = parentItem;
-            index = parent;
-        }
-        this.nodes[index] = item;
+    fix() {
+        for (let i = Math.floor(this.size / 2); i >= 0; i--)
+            this._sinkDown(i, this.elements.length >> 1);
     }
     /**
      * Time Complexity: O(log n)
@@ -299,40 +299,50 @@ export class Heap {
      * 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.
+     * Float operation to maintain heap properties after adding an element.
+     * @param index - The index of the newly added element.
      */
-    sinkDown(index) {
-        const leftChildIndex = index << 1 | 1;
-        const rightChildIndex = leftChildIndex + 1;
-        const length = this.nodes.length;
-        let targetIndex = index;
-        if (leftChildIndex < length && this.comparator(this.nodes[leftChildIndex], this.nodes[targetIndex]) < 0) {
-            targetIndex = leftChildIndex;
-        }
-        if (rightChildIndex < length && this.comparator(this.nodes[rightChildIndex], this.nodes[targetIndex]) < 0) {
-            targetIndex = rightChildIndex;
-        }
-        if (targetIndex !== index) {
-            const temp = this.nodes[index];
-            this.nodes[index] = this.nodes[targetIndex];
-            this.nodes[targetIndex] = temp;
-            this.sinkDown(targetIndex);
+    _bubbleUp(index) {
+        const element = this.elements[index];
+        while (index > 0) {
+            const parent = (index - 1) >> 1;
+            const parentItem = this.elements[parent];
+            if (this._comparator(parentItem, element) <= 0)
+                break;
+            this.elements[index] = parentItem;
+            index = parent;
         }
+        this.elements[index] = element;
     }
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(n)
+     * Time Complexity: O(log n)
      * Space Complexity: O(1)
      *
-     * Fix the entire heap to maintain heap properties.
-     */
-    fix() {
-        for (let i = Math.floor(this.size / 2); i >= 0; i--)
-            this.sinkDown(i);
+     * Sinking operation to maintain heap properties after removing the top element.
+     * @param index - The index from which to start sinking.
+     * @param halfLength
+     */
+    _sinkDown(index, halfLength) {
+        const element = this.elements[index];
+        while (index < halfLength) {
+            let left = index << 1 | 1;
+            const right = left + 1;
+            let minItem = this.elements[left];
+            if (right < this.elements.length &&
+                this._comparator(minItem, this.elements[right]) > 0) {
+                left = right;
+                minItem = this.elements[right];
+            }
+            if (this._comparator(minItem, element) >= 0)
+                break;
+            this.elements[index] = minItem;
+            index = left;
+        }
+        this.elements[index] = element;
     }
 }
 export class FibonacciHeapNode {
@@ -436,22 +446,22 @@ export class FibonacciHeap {
         return this.min ? this.min.element : undefined;
     }
     /**
-     * Time Complexity: O(n), where n is the number of nodes in the linked list.
+     * Time Complexity: O(n), where n is the number of elements in the linked list.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(n), where n is the number of nodes in the linked list.
+     * 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 nodes of the linked list.
+     * @returns FibonacciHeapNode<E>[] - An array containing the elements of the linked list.
      */
     consumeLinkedList(head) {
-        const nodes = [];
+        const elements = [];
         if (!head)
-            return nodes;
+            return elements;
         let node = head;
         let flag = false;
         while (true) {
@@ -460,11 +470,11 @@ export class FibonacciHeap {
             else if (node === head)
                 flag = true;
             if (node) {
-                nodes.push(node);
+                elements.push(node);
                 node = node.right;
             }
         }
-        return nodes;
+        return elements;
     }
     /**
      * Time Complexity: O(1)
@@ -485,11 +495,11 @@ export class FibonacciHeap {
         }
     }
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      *
      * Remove and return the top element (smallest or largest element) from the heap.
@@ -499,11 +509,11 @@ export class FibonacciHeap {
         return this.pop();
     }
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      */
     /**
-     * Time Complexity: O(log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(log n), where n is the number of elements in the heap.
      * Space Complexity: O(1)
      *
      * Remove and return the top element (smallest or largest element) from the heap.
@@ -514,8 +524,8 @@ export class FibonacciHeap {
             return undefined;
         const z = this.min;
         if (z.child) {
-            const nodes = this.consumeLinkedList(z.child);
-            for (const node of nodes) {
+            const elements = this.consumeLinkedList(z.child);
+            for (const node of elements) {
                 this.mergeWithRoot(node);
                 node.parent = undefined;
             }
@@ -652,11 +662,11 @@ export class FibonacciHeap {
         y.parent = x;
     }
     /**
-     * Time Complexity: O(n log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(n log n), where n is the number of elements in the heap.
      * Space Complexity: O(n)
      */
     /**
-     * Time Complexity: O(n log n), where n is the number of nodes in the heap.
+     * Time Complexity: O(n log n), where n is the number of elements in the heap.
      * Space Complexity: O(n)
      *
      * Remove and return the top element (smallest or largest element) from the heap.
@@ -664,9 +674,9 @@ export class FibonacciHeap {
      */
     consolidate() {
         const A = new Array(this.size);
-        const nodes = this.consumeLinkedList(this.root);
+        const elements = this.consumeLinkedList(this.root);
         let x, y, d, t;
-        for (const node of nodes) {
+        for (const node of elements) {
             x = node;
             d = x.degree;
             while (A[d]) {