min-heap-typed 1.50.1 → 1.50.3

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

@@ -17,13 +17,17 @@ import { calcMinUnitsRequired, rangeCheck } from '../../utils';
  * 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;
-  protected _bucketLast = 0;
-  protected _lastInBucket = 0;
-  protected _bucketCount = 0;
-  protected readonly _bucketSize: number = 1 << 12;
-
+  /**
+   * The constructor initializes a Deque object with an optional iterable of elements and options.
+   * @param elements - An iterable object (such as an array or a Set) that contains the initial
+   * elements to be added to the deque. It can also be an object with a `length` or `size` property
+   * that represents the number of elements in the iterable object. If no elements are provided, an
+   * empty deque
+   * @param {DequeOptions} [options] - The `options` parameter is an optional object that can contain
+   * configuration options for the deque. In this code, it is used to set the `bucketSize` option,
+   * which determines the size of each bucket in the deque. If the `bucketSize` option is not provided
+   * or is not a number
+   */
   constructor(elements: IterableWithSizeOrLength<E> = [], options?: DequeOptions) {
     super();
 
@@ -54,14 +58,85 @@ export class Deque<E> extends IterableElementBase<E> {
     }
   }
 
+  protected _bucketSize: number = 1 << 12;
+
+  /**
+   * The bucketSize function returns the size of the bucket.
+   *
+   * @return The size of the bucket
+   */
+  get bucketSize() {
+    return this._bucketSize;
+  }
+
+  protected _bucketFirst = 0;
+
+  /**
+   * The function returns the value of the protected variable `_bucketFirst`.
+   * @returns The value of the `_bucketFirst` property.
+   */
+  get bucketFirst(): number {
+    return this._bucketFirst;
+  }
+
+  protected _firstInBucket = 0;
+
+  /**
+   * The function returns the value of the protected variable _firstInBucket.
+   * @returns The method is returning the value of the variable `_firstInBucket`, which is of type
+   * `number`.
+   */
+  get firstInBucket(): number {
+    return this._firstInBucket;
+  }
+
+  protected _bucketLast = 0;
+
+  /**
+   * The function returns the value of the protected variable `_bucketLast`.
+   * @returns The value of the `_bucketLast` property, which is a number.
+   */
+  get bucketLast(): number {
+    return this._bucketLast;
+  }
+
+  protected _lastInBucket = 0;
+
+  /**
+   * The function returns the value of the protected variable _lastInBucket.
+   * @returns The method is returning the value of the variable `_lastInBucket`, which is of type
+   * `number`.
+   */
+  get lastInBucket(): number {
+    return this._lastInBucket;
+  }
+
+  protected _bucketCount = 0;
+
+  /**
+   * The function returns the number of buckets.
+   * @returns The number of buckets.
+   */
+  get bucketCount(): number {
+    return this._bucketCount;
+  }
+
   protected _buckets: E[][] = [];
 
+  /**
+   * The buckets function returns the buckets property of the object.
+   * @return The buckets property
+   */
   get buckets() {
     return this._buckets;
   }
 
   protected _size = 0;
 
+  /**
+   * The size function returns the number of items in the stack.
+   * @return The number of values in the set
+   */
   get size() {
     return this._size;
   }
@@ -76,6 +151,10 @@ export class Deque<E> extends IterableElementBase<E> {
     return this._buckets[this._bucketFirst][this._firstInBucket];
   }
 
+  /**
+   * The last function returns the last element in the queue.
+   * @return The last element in the array
+   */
   get last(): E | undefined {
     if (this.size === 0) return;
     return this._buckets[this._bucketLast][this._lastInBucket];
@@ -210,15 +289,30 @@ export class Deque<E> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(1) - Removes the last element.
-   * Space Complexity: O(1) - Operates in-place.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
    */
 
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function checks if the size of an object is equal to zero and returns a boolean value.
+   * @returns A boolean value indicating whether the size of the object is 0 or not.
+   */
   isEmpty(): boolean {
     return this.size === 0;
   }
 
   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
    * The clear() function resets the state of the object by initializing all variables to their default
    * values.
    */
@@ -235,7 +329,7 @@ export class Deque<E> extends IterableElementBase<E> {
   * begin(): Generator<E> {
     let index = 0;
     while (index < this.size) {
-      yield this.getAt(index);
+      yield this.at(index);
       index++;
     }
   }
@@ -247,7 +341,7 @@ export class Deque<E> extends IterableElementBase<E> {
   * reverseBegin(): Generator<E> {
     let index = this.size - 1;
     while (index >= 0) {
-      yield this.getAt(index);
+      yield this.at(index);
       index--;
     }
   }
@@ -261,13 +355,13 @@ export class Deque<E> extends IterableElementBase<E> {
    * Time Complexity: O(1)
    * Space Complexity: O(1)
    *
-   * The `getAt` function retrieves an element at a specified position in an array-like data structure.
+   * The `at` function retrieves an element at a specified position in an array-like data structure.
    * @param {number} pos - The `pos` parameter represents the position of the element that you want to
    * retrieve from the data structure. It is of type `number` and should be a valid index within the
    * range of the data structure.
    * @returns The element at the specified position in the data structure is being returned.
    */
-  getAt(pos: number): E {
+  at(pos: number): E {
     rangeCheck(pos, 0, this.size - 1);
     const { bucketIndex, indexInBucket } = this._getBucketAndPosition(pos);
     return this._buckets[bucketIndex][indexInBucket]!;
@@ -325,9 +419,9 @@ export class Deque<E> extends IterableElementBase<E> {
     } else {
       const arr: E[] = [];
       for (let i = pos; i < this.size; ++i) {
-        arr.push(this.getAt(i));
+        arr.push(this.at(i));
       }
-      this.cut(pos - 1);
+      this.cut(pos - 1, true);
       for (let i = 0; i < num; ++i) this.push(element);
       for (let i = 0; i < arr.length; ++i) this.push(arr[i]);
     }
@@ -347,28 +441,81 @@ export class Deque<E> extends IterableElementBase<E> {
    * updated size.
    * @param {number} pos - The `pos` parameter represents the position at which the string should be
    * cut. It is a number that indicates the index of the character where the cut should be made.
+   * @param {boolean} isCutSelf - If true, the original deque will not be cut, and return a new deque
    * @returns The method is returning the updated size of the data structure.
    */
-  cut(pos: number): number {
-    if (pos < 0) {
-      this.clear();
-      return 0;
+  cut(pos: number, isCutSelf = false): Deque<E> {
+    if (isCutSelf) {
+      if (pos < 0) {
+        this.clear();
+        return this;
+      }
+      const { bucketIndex, indexInBucket } = this._getBucketAndPosition(pos);
+      this._bucketLast = bucketIndex;
+      this._lastInBucket = indexInBucket;
+      this._size = pos + 1;
+      return this;
+    } else {
+      const newDeque = new Deque<E>([], { bucketSize: this._bucketSize });
+
+      for (let i = 0; i <= pos; i++) {
+        newDeque.push(this.at(i));
+      }
+
+      return newDeque;
+    }
+  }
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1) or O(n)
+   */
+
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1) or O(n)
+   *
+   * The `cutRest` function cuts the elements from a specified position in a deque and returns a new
+   * deque with the cut elements.
+   * @param {number} pos - The `pos` parameter represents the position from which to cut the Deque. It
+   * is a number that indicates the index of the element in the Deque where the cut should start.
+   * @param [isCutSelf=false] - isCutSelf is a boolean parameter that determines whether the original
+   * Deque should be modified or a new Deque should be created. If isCutSelf is true, the original
+   * Deque will be modified by cutting off elements starting from the specified position. If isCutSelf
+   * is false, a new De
+   * @returns The function `cutRest` returns either the modified original deque (`this`) or a new deque
+   * (`newDeque`) depending on the value of the `isCutSelf` parameter.
+   */
+  cutRest(pos: number, isCutSelf = false): Deque<E> {
+    if (isCutSelf) {
+      if (pos < 0) {
+        this.clear();
+        return this;
+      }
+      const { bucketIndex, indexInBucket } = this._getBucketAndPosition(pos);
+      this._bucketFirst = bucketIndex;
+      this._firstInBucket = indexInBucket;
+      this._size = this._size - pos;
+      return this;
+    } else {
+      const newDeque = new Deque<E>([], { bucketSize: this._bucketSize });
+
+      for (let i = pos; i < this.size; i++) {
+        newDeque.push(this.at(i));
+      }
+
+      return newDeque;
     }
-    const { bucketIndex, indexInBucket } = this._getBucketAndPosition(pos);
-    this._bucketLast = bucketIndex;
-    this._lastInBucket = indexInBucket;
-    this._size = pos + 1;
-    return this.size;
   }
 
   /**
    * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * Space Complexity: O(1) or O(n)
    */
 
   /**
    * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * Space Complexity: O(1) or O(n)
    *
    * The `deleteAt` function removes an element at a specified position in an array-like data
    * structure.
@@ -416,14 +563,14 @@ export class Deque<E> extends IterableElementBase<E> {
     let i = 0;
     let index = 0;
     while (i < size) {
-      const oldElement = this.getAt(i);
+      const oldElement = this.at(i);
       if (oldElement !== element) {
         this.setAt(index, oldElement!);
         index += 1;
       }
       i += 1;
     }
-    this.cut(index - 1);
+    this.cut(index - 1, true);
     return true;
   }
 
@@ -471,15 +618,15 @@ export class Deque<E> extends IterableElementBase<E> {
       return this;
     }
     let index = 1;
-    let prev = this.getAt(0);
+    let prev = this.at(0);
     for (let i = 1; i < this.size; ++i) {
-      const cur = this.getAt(i);
+      const cur = this.at(i);
       if (cur !== prev) {
         prev = cur;
         this.setAt(index++, cur);
       }
     }
-    this.cut(index - 1);
+    this.cut(index - 1, true);
     return this;
   }
 
@@ -501,7 +648,7 @@ export class Deque<E> extends IterableElementBase<E> {
   sort(comparator?: (x: E, y: E) => number): this {
     const arr: E[] = [];
     for (let i = 0; i < this.size; ++i) {
-      arr.push(this.getAt(i));
+      arr.push(this.at(i));
     }
     arr.sort(comparator);
     for (let i = 0; i < this.size; ++i) {
@@ -545,32 +692,6 @@ export class Deque<E> extends IterableElementBase<E> {
     this._buckets = newBuckets;
   }
 
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   *
-   * The `find` function iterates over the elements in a deque and returns the first element for which
-   * the callback function returns true, or undefined if no such element is found.
-   * @param callback - A function that takes three parameters: element, index, and deque. It should
-   * return a boolean value indicating whether the element satisfies a certain condition.
-   * @returns The method `find` returns the first element in the deque that satisfies the condition
-   * specified by the callback function. If no element satisfies the condition, it returns `undefined`.
-   */
-  find(callback: (element: E, index: number, deque: Deque<E>) => boolean): E | undefined {
-    for (let i = 0; i < this.size; ++i) {
-      const element = this.getAt(i);
-      if (callback(element, i, this)) {
-        return element;
-      }
-    }
-    return;
-  }
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -589,7 +710,7 @@ export class Deque<E> extends IterableElementBase<E> {
    */
   indexOf(element: E): number {
     for (let i = 0; i < this.size; ++i) {
-      if (this.getAt(i) === element) {
+      if (this.at(i) === element) {
         return i;
       }
     }
@@ -616,6 +737,25 @@ export class Deque<E> extends IterableElementBase<E> {
    * Time Complexity: O(n)
    * Space Complexity: O(n)
    */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `clone()` function returns a new instance of the `Deque` class with the same elements and
+   * bucket size as the original instance.
+   * @returns The `clone()` method is returning a new instance of the `Deque` class with the same
+   * elements as the original deque (`this`) and the same bucket size.
+   */
+  clone(): Deque<E> {
+    return new Deque<E>([...this], { bucketSize: this.bucketSize });
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -677,8 +817,8 @@ export class Deque<E> extends IterableElementBase<E> {
    */
 
   /**
-   * Time Complexity: O(1)
-   * Space Complexity: O(n) - In worst case, resizing doubles the array size.
+   * Time Complexity: Amortized O(1) - Similar to push, resizing leads to O(n).
+   * Space Complexity: O(n) - Due to potential resizing.
    *
    * 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
@@ -689,13 +829,13 @@ export class Deque<E> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(1) - Removes the first element.
-   * Space Complexity: O(1) - In-place operation.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
    */
 
   /**
-   * Time Complexity: O(1) - Removes the last element.
-   * Space Complexity: O(1) - Operates in-place.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
    *
    * The function "pollLast" removes and returns the last element of an array.
    * @returns The last element of the array is being returned.
@@ -705,8 +845,13 @@ export class Deque<E> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(1).
-   * Space Complexity: O(n) - Due to potential resizing.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   * /
+
+   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
    *
    * 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
@@ -717,8 +862,13 @@ export class Deque<E> extends IterableElementBase<E> {
   }
 
   /**
-   * Time Complexity: O(1) - Removes the first element.
-   * Space Complexity: O(1) - In-place operation.
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   * /
+
+   /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
    *
    * 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
@@ -729,6 +879,11 @@ export class Deque<E> extends IterableElementBase<E> {
   }
 
   /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   * /
+
+   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
    *
@@ -737,7 +892,7 @@ export class Deque<E> extends IterableElementBase<E> {
    */
   protected* _getIterator(): IterableIterator<E> {
     for (let i = 0; i < this.size; ++i) {
-      yield this.getAt(i);
+      yield this.at(i);
     }
   }