heap-typed 1.49.0 → 1.49.2

package/src/data-structures/queue/deque.ts

@@ -5,19 +5,17 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-
-
-import { ElementCallback, IterableWithSizeOrLength } from "../../types";
-import { calcMinUnitsRequired, rangeCheck } from "../../utils";
+import type { ElementCallback, IterableWithSizeOrLength } from "../../types";
 import { IterableElementBase } from "../base";
+import { calcMinUnitsRequired, rangeCheck } from "../../utils";
 
 /**
- * Deque can provide random access with O(1) time complexity
- * Deque is usually more compact and efficient in memory usage because it does not require additional space to store pointers.
- * Deque may experience performance jitter, but DoublyLinkedList will not
- * Deque is implemented using a dynamic array. Inserting or deleting beyond both ends of the array may require moving elements or reallocating space.
+ * 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
  */
-
 export class Deque<E> extends IterableElementBase<E> {
   protected _bucketFirst = 0;
   protected _firstInBucket = 0;
@@ -85,106 +83,6 @@ export class Deque<E> extends IterableElementBase<E> {
     return this._buckets[this._bucketLast][this._lastInBucket];
   }
 
-  /**
-   * Time Complexity: O(1) - Removes the last element.
-   * Space Complexity: O(1) - Operates in-place.
-   */
-
-  isEmpty() {
-    return this.size === 0;
-  }
-
-  /**
-   * Time Complexity: Amortized O(1) - Similar to push, resizing leads to O(n).
-   * Space Complexity: O(n) - Due to potential resizing.
-   */
-
-  /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(n) - In worst case, resizing doubles the array size.
-   *
-   * The addLast function adds an element to the end of an array.
-   * @param {E} element - The element parameter represents the element that you want to add to the end of the
-   * data structure.
-   */
-  addLast(element: E): void {
-    this.push(element);
-  }
-
-  /**
-   * Time Complexity: O(1) - Removes the first element.
-   * Space Complexity: O(1) - In-place operation.
-   */
-
-  /**
-   * Time Complexity: O(1) - Removes the last element.
-   * Space Complexity: O(1) - Operates in-place.
-   *
-   * The function "pollLast" removes and returns the last element of an array.
-   * @returns The last element of the array is being returned.
-   */
-  pollLast(): E | undefined {
-    return this.pop();
-  }
-
-  /**
-   * Time Complexity: O(1).
-   * Space Complexity: O(n) - Due to potential resizing.
-   *
-   * The "addFirst" function adds an element to the beginning of an array.
-   * @param {E} element - The parameter "element" represents the element that you want to add to the
-   * beginning of the data structure.
-   */
-  addFirst(element: E): void {
-    this.unshift(element);
-  }
-
-  /**
-   * Time Complexity: O(1) - Removes the first element.
-   * Space Complexity: O(1) - In-place operation.
-   *
-   * The function "pollFirst" removes and returns the first element of an array.
-   * @returns The method `pollFirst()` is returning the first element of the array after removing it
-   * from the beginning. If the array is empty, it will return `undefined`.
-   */
-  pollFirst(): E | undefined {
-    return this.shift();
-  }
-
-  /**
-   * The clear() function resets the state of the object by initializing all variables to their default
-   * values.
-   */
-  clear() {
-    this._buckets = [new Array(this._bucketSize)];
-    this._bucketCount = 1;
-    this._bucketFirst = this._bucketLast = this._size = 0;
-    this._firstInBucket = this._lastInBucket = this._bucketSize >> 1;
-  }
-
-  /**
-   * The below function is a generator that yields elements from a collection one by one.
-   */
-  * begin(): Generator<E> {
-    let index = 0;
-    while (index < this.size) {
-      yield this.getAt(index);
-      index++;
-    }
-  }
-
-  /**
-   * The function `reverseBegin()` is a generator that yields elements in reverse order starting from
-   * the last element.
-   */
-  * reverseBegin(): Generator<E> {
-    let index = this.size - 1;
-    while (index >= 0) {
-      yield this.getAt(index);
-      index--;
-    }
-  }
-
   /**
    * Time Complexity - Amortized O(1) (possible reallocation)
    * Space Complexity - O(n) (due to potential resizing).
@@ -199,7 +97,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * structure.
    * @returns The size of the data structure after the element has been pushed.
    */
-  push(element: E) {
+  push(element: E): boolean {
     if (this.size) {
       if (this._lastInBucket < this._bucketSize - 1) {
         this._lastInBucket += 1;
@@ -217,7 +115,7 @@ export class Deque<E> extends IterableElementBase<E> {
     }
     this._size += 1;
     this._buckets[this._bucketLast][this._lastInBucket] = element;
-    return this.size;
+    return true;
   }
 
   /**
@@ -233,7 +131,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * internal state variables accordingly.
    * @returns The element that was removed from the data structure is being returned.
    */
-  pop() {
+  pop(): E | undefined {
     if (this.size === 0) return;
     const element = this._buckets[this._bucketLast][this._lastInBucket];
     if (this.size !== 1) {
@@ -266,7 +164,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * beginning of the data structure.
    * @returns The size of the data structure after the element has been added.
    */
-  unshift(element: E) {
+  unshift(element: E): boolean {
     if (this.size) {
       if (this._firstInBucket > 0) {
         this._firstInBucket -= 1;
@@ -284,10 +182,9 @@ export class Deque<E> extends IterableElementBase<E> {
     }
     this._size += 1;
     this._buckets[this._bucketFirst][this._firstInBucket] = element;
-    return this.size;
+    return true;
   }
 
-
   /**
    * Time Complexity: O(1)
    * Space Complexity: O(1)
@@ -302,7 +199,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * @returns The element that is being removed from the beginning of the data structure is being
    * returned.
    */
-  shift() {
+  shift(): E | undefined {
     if (this.size === 0) return;
     const element = this._buckets[this._bucketFirst][this._firstInBucket];
     if (this.size !== 1) {
@@ -320,6 +217,49 @@ export class Deque<E> extends IterableElementBase<E> {
     return element;
   }
 
+  /**
+   * Time Complexity: O(1) - Removes the last element.
+   * Space Complexity: O(1) - Operates in-place.
+   */
+
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+
+  /**
+   * The clear() function resets the state of the object by initializing all variables to their default
+   * values.
+   */
+  clear(): void {
+    this._buckets = [new Array(this._bucketSize)];
+    this._bucketCount = 1;
+    this._bucketFirst = this._bucketLast = this._size = 0;
+    this._firstInBucket = this._lastInBucket = this._bucketSize >> 1;
+  }
+
+  /**
+   * The below function is a generator that yields elements from a collection one by one.
+   */
+  * begin(): Generator<E> {
+    let index = 0;
+    while (index < this.size) {
+      yield this.getAt(index);
+      index++;
+    }
+  }
+
+  /**
+   * The function `reverseBegin()` is a generator that yields elements in reverse order starting from
+   * the last element.
+   */
+  * reverseBegin(): Generator<E> {
+    let index = this.size - 1;
+    while (index >= 0) {
+      yield this.getAt(index);
+      index--;
+    }
+  }
+
 
   /**
    * Time Complexity: O(1)
@@ -361,13 +301,14 @@ export class Deque<E> extends IterableElementBase<E> {
    * @param {E} element - The `element` parameter is the value that you want to set at the specified
    * position in the data structure.
    */
-  setAt(pos: number, element: E) {
+  setAt(pos: number, element: E): boolean {
     rangeCheck(pos, 0, this.size - 1);
     const {
       bucketIndex,
       indexInBucket
     } = this._getBucketAndPosition(pos);
     this._buckets[bucketIndex][indexInBucket] = element;
+    return true;
   }
 
   /**
@@ -379,7 +320,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * Time Complexity: O(n)
    * Space Complexity: O(n)
    *
-   * The `insertAt` function inserts one or more elements at a specified position in an array-like data
+   * The `addAt` function inserts one or more elements at a specified position in an array-like data
    * structure.
    * @param {number} pos - The `pos` parameter represents the position at which the element(s) should
    * be inserted. It is of type `number`.
@@ -390,7 +331,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * will be inserted once. However, you can provide a different value for `num` if you want
    * @returns The size of the array after the insertion is being returned.
    */
-  insertAt(pos: number, element: E, num = 1) {
+  addAt(pos: number, element: E, num = 1): boolean {
     const length = this.size;
     rangeCheck(pos, 0, length);
     if (pos === 0) {
@@ -406,7 +347,7 @@ export class Deque<E> extends IterableElementBase<E> {
       for (let i = 0; i < num; ++i) this.push(element);
       for (let i = 0; i < arr.length; ++i) this.push(arr[i]);
     }
-    return this.size;
+    return true;
   }
 
   /**
@@ -424,7 +365,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * cut. It is a number that indicates the index of the character where the cut should be made.
    * @returns The method is returning the updated size of the data structure.
    */
-  cut(pos: number) {
+  cut(pos: number): number {
     if (pos < 0) {
       this.clear();
       return 0;
@@ -455,7 +396,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * the index of the element to be deleted.
    * @returns The size of the data structure after the deletion operation is performed.
    */
-  deleteAt(pos: number) {
+  deleteAt(pos: number): boolean {
     rangeCheck(pos, 0, this.size - 1);
     if (pos === 0) this.shift();
     else if (pos === this.size - 1) this.pop();
@@ -476,7 +417,7 @@ export class Deque<E> extends IterableElementBase<E> {
       }
       this.pop();
     }
-    return this.size;
+    return true;
   }
 
   /**
@@ -494,9 +435,9 @@ export class Deque<E> extends IterableElementBase<E> {
    * the data structure.
    * @returns The size of the data structure after the element has been deleted.
    */
-  delete(element: E) {
+  delete(element: E): boolean {
     const size = this.size;
-    if (size === 0) return 0;
+    if (size === 0) return false;
     let i = 0;
     let index = 0;
     while (i < size) {
@@ -508,7 +449,7 @@ export class Deque<E> extends IterableElementBase<E> {
       i += 1;
     }
     this.cut(index - 1);
-    return this.size;
+    return true;
   }
 
   /**
@@ -525,7 +466,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * @returns The reverse() method is returning the object itself (this) after performing the reverse
    * operation on the buckets and updating the relevant properties.
    */
-  reverse() {
+  reverse(): this {
     this._buckets.reverse().forEach(function (bucket) {
       bucket.reverse();
     });
@@ -550,9 +491,9 @@ export class Deque<E> extends IterableElementBase<E> {
    * the number of unique elements.
    * @returns The size of the modified array is being returned.
    */
-  unique() {
+  unique(): this {
     if (this.size <= 1) {
-      return this.size;
+      return this;
     }
     let index = 1;
     let prev = this.getAt(0);
@@ -564,7 +505,7 @@ export class Deque<E> extends IterableElementBase<E> {
       }
     }
     this.cut(index - 1);
-    return this.size;
+    return this;
   }
 
   /**
@@ -580,9 +521,9 @@ export class Deque<E> extends IterableElementBase<E> {
    * @param [comparator] - The `comparator` parameter is a function that takes in two elements `x` and
    * `y` of type `E` and returns a number. The comparator function is used to determine the order of
    * the elements in the sorted array.
-   * @returns The method is returning the sorted instance of the object on which the method is called.
+   * @returns Deque<E>
    */
-  sort(comparator?: (x: E, y: E) => number) {
+  sort(comparator?: (x: E, y: E) => number): this {
     const arr: E[] = [];
     for (let i = 0; i < this.size; ++i) {
       arr.push(this.getAt(i));
@@ -608,7 +549,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * @returns Nothing is being returned. The function is using the `return` statement to exit early if
    * `this.size` is 0, but it does not return any value.
    */
-  shrinkToFit() {
+  shrinkToFit(): void {
     if (this.size === 0) return;
     const newBuckets = [];
     if (this._bucketFirst === this._bucketLast) return;
@@ -652,7 +593,7 @@ export class Deque<E> extends IterableElementBase<E> {
         return element;
       }
     }
-    return undefined;
+    return;
   }
 
   /**
@@ -693,11 +634,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * @returns The `toArray()` method is returning an array of elements of type `E`.
    */
   toArray(): E[] {
-    const arr: E[] = [];
-    for (let i = 0; i < this.size; ++i) {
-      arr.push(this.getAt(i));
-    }
-    return arr;
+    return [...this];
   }
 
   /**
@@ -760,12 +697,60 @@ export class Deque<E> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
+   * Time Complexity: Amortized O(1) - Similar to push, resizing leads to O(n).
+   * Space Complexity: O(n) - Due to potential resizing.
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(n) - In worst case, resizing doubles the array size.
+   *
+   * The addLast function adds an element to the end of an array.
+   * @param {E} element - The element parameter represents the element that you want to add to the end of the
+   * data structure.
+   */
+  addLast(element: E): boolean {
+    return this.push(element);
+  }
+
+  /**
+   * Time Complexity: O(1) - Removes the first element.
+   * Space Complexity: O(1) - In-place operation.
+   */
+
+  /**
+   * Time Complexity: O(1) - Removes the last element.
+   * Space Complexity: O(1) - Operates in-place.
+   *
+   * The function "pollLast" removes and returns the last element of an array.
+   * @returns The last element of the array is being returned.
    */
+  pollLast(): E | undefined {
+    return this.pop();
+  }
 
-  print(): void {
-    console.log([...this])
+  /**
+   * Time Complexity: O(1).
+   * Space Complexity: O(n) - Due to potential resizing.
+   *
+   * The "addFirst" function adds an element to the beginning of an array.
+   * @param {E} element - The parameter "element" represents the element that you want to add to the
+   * beginning of the data structure.
+   */
+  addFirst(element: E): boolean {
+    return this.unshift(element);
+  }
+
+  /**
+   * Time Complexity: O(1) - Removes the first element.
+   * Space Complexity: O(1) - In-place operation.
+   *
+   * The function "pollFirst" removes and returns the first element of an array.
+   * @returns The method `pollFirst()` is returning the first element of the array after removing it
+   * from the beginning. If the array is empty, it will return `undefined`.
+   */
+  pollFirst(): E | undefined {
+    return this.shift();
   }
 
   /**
@@ -775,7 +760,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * The above function is an implementation of the iterator protocol in TypeScript, allowing the
    * object to be iterated over using a for...of loop.
    */
-  protected* _getIterator() {
+  protected* _getIterator(): IterableIterator<E> {
     for (let i = 0; i < this.size; ++i) {
       yield this.getAt(i);
     }

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

@@ -3,10 +3,19 @@
  * @copyright Tyler Zeng <zrwusa@gmail.com>
  * @class
  */
-import { SinglyLinkedList } from '../linked-list';
+import type { ElementCallback } from '../../types';
 import { IterableElementBase } from "../base";
-import { ElementCallback } from "../../types";
+import { SinglyLinkedList } from '../linked-list';
 
+/**
+ * 1. First In, First Out (FIFO): The core feature of a queue is its first in, first out nature. The element added to the queue first will be the one to be removed first.
+ * 2. Operations: The main operations include enqueue (adding an element to the end of the queue) and dequeue (removing and returning the element at the front of the queue). Typically, there is also a peek operation (looking at the front element without removing it).
+ * 3. Uses: Queues are commonly used to manage a series of tasks or elements that need to be processed in order. For example, managing task queues in a multi-threaded environment, or in algorithms for data structures like trees and graphs for breadth-first search.
+ * 4. Task Scheduling: Managing the order of task execution in operating systems or applications.
+ * 5. Data Buffering: Acting as a buffer for data packets in network communication.
+ * 6. Breadth-First Search (BFS): In traversal algorithms for graphs and trees, queues store nodes that are to be visited.
+ * 7. Real-time Queuing: Like queuing systems in banks or supermarkets.
+ */
 export class Queue<E = any> extends IterableElementBase<E> {
   /**
    * The constructor initializes an instance of a class with an optional array of elements and sets the offset to 0.
@@ -65,9 +74,9 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * @param {E} element - The `element` parameter represents the element that you want to add to the queue.
    * @returns The `add` method is returning a `Queue<E>` object.
    */
-  push(element: E): Queue<E> {
+  push(element: E): boolean {
     this.nodes.push(element);
-    return this;
+    return true;
   }
 
   /**
@@ -86,7 +95,7 @@ export class Queue<E = any> extends IterableElementBase<E> {
   shift(): E | undefined {
     if (this.size === 0) return undefined;
 
-    const first = this.getFirst();
+    const first = this.first;
     this._offset += 1;
 
     if (this.offset * 2 < this.nodes.length) return first;
@@ -107,11 +116,11 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * Time Complexity: O(1) - constant time as it retrieves the value at the current offset.
    * Space Complexity: O(1) - no additional space is used.
    *
-   * The `getFirst` function returns the first element of the array `_nodes` if it exists, otherwise it returns `undefined`.
-   * @returns The `getFirst()` method returns the first element of the data structure, represented by the `_nodes` array at
+   * The `first` function returns the first element of the array `_nodes` if it exists, otherwise it returns `undefined`.
+   * @returns The `get first()` method returns the first element of the data structure, represented by the `_nodes` array at
    * the `_offset` index. If the data structure is empty (size is 0), it returns `undefined`.
    */
-  getFirst(): E | undefined {
+  get first(): E | undefined {
     return this.size > 0 ? this.nodes[this.offset] : undefined;
   }
 
@@ -129,7 +138,7 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * the `_offset` index. If the data structure is empty (size is 0), it returns `undefined`.
    */
   peek(): E | undefined {
-    return this.getFirst();
+    return this.first;
   }
 
   /**
@@ -141,11 +150,11 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * Time Complexity: O(1) - constant time as it retrieves the value at the current offset.
    * Space Complexity: O(1) - no additional space is used.
    *
-   * The `getLast` function returns the last element in an array-like data structure, or undefined if the structure is empty.
-   * @returns The method `getLast()` returns the last element of the `_nodes` array if the array is not empty. If the
+   * The `last` function returns the last element in an array-like data structure, or undefined if the structure is empty.
+   * @returns The method `get last()` returns the last element of the `_nodes` array if the array is not empty. If the
    * array is empty, it returns `undefined`.
    */
-  getLast(): E | undefined {
+  get last(): E | undefined {
     return this.size > 0 ? this.nodes[this.nodes.length - 1] : undefined;
   }
 
@@ -163,7 +172,7 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * array is empty, it returns `undefined`.
    */
   peekLast(): E | undefined {
-    return this.getLast();
+    return this.last;
   }
 
   /**
@@ -178,8 +187,8 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * The enqueue function adds a value to the end of a queue.
    * @param {E} value - The value parameter represents the value that you want to add to the queue.
    */
-  enqueue(value: E) {
-    this.push(value);
+  enqueue(value: E): boolean {
+    return this.push(value);
   }
 
   /**
@@ -269,10 +278,6 @@ export class Queue<E = any> extends IterableElementBase<E> {
     return new Queue(this.nodes.slice(this.offset));
   }
 
-  print(): void {
-    console.log([...this]);
-  }
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -339,20 +344,26 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * Space Complexity: O(n)
    */
 
-  protected* _getIterator() {
+  protected* _getIterator(): IterableIterator<E> {
     for (const item of this.nodes) {
       yield item;
     }
   }
 }
 
+/**
+ * 1. First In, First Out (FIFO) Strategy: Like other queue implementations, LinkedListQueue follows the first in, first out principle, meaning the element that is added to the queue first will be the first to be removed.
+ * 2. Based on Linked List: LinkedListQueue uses a linked list to store elements. Each node in the linked list contains data and a pointer to the next node.
+ * 3. Memory Usage: Since each element requires additional space to store a pointer to the next element, linked lists may use more memory compared to arrays.
+ * 4. Frequent Enqueuing and Dequeuing Operations: If your application involves frequent enqueuing and dequeuing operations and is less concerned with random access, then LinkedListQueue is a good choice.
+ */
 export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
   /**
    * The enqueue function adds a value to the end of an array.
    * @param {E} value - The value parameter represents the value that you want to add to the queue.
    */
-  enqueue(value: E) {
-    this.push(value);
+  enqueue(value: E): boolean {
+    return  this.push(value);
   }
 
   /**
@@ -364,10 +375,10 @@ export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
   }
 
   /**
-   * The `getFirst` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
-   * @returns The `getFirst()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
+   * The `get first` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
+   * @returns The `get first()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
    */
-  getFirst(): E | undefined {
+  get first(): E | undefined {
     return this.head?.value;
   }
 
@@ -376,6 +387,6 @@ export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
    * @returns The `peek()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
    */
   peek(): E | undefined {
-    return this.getFirst();
+    return this.first;
   }
 }