data-structure-typed 1.50.1 → 1.50.3

package/dist/mjs/data-structures/queue/deque.js

@@ -8,12 +8,17 @@ import { calcMinUnitsRequired, rangeCheck } from '../../utils';
  * 5. Performance jitter: Deque may experience performance jitter, but DoublyLinkedList will not
  */
 export class Deque extends IterableElementBase {
-    _bucketFirst = 0;
-    _firstInBucket = 0;
-    _bucketLast = 0;
-    _lastInBucket = 0;
-    _bucketCount = 0;
-    _bucketSize = 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 = [], options) {
         super();
         if (options) {
@@ -45,11 +50,70 @@ export class Deque extends IterableElementBase {
             this.push(element);
         }
     }
+    _bucketSize = 1 << 12;
+    /**
+     * The bucketSize function returns the size of the bucket.
+     *
+     * @return The size of the bucket
+     */
+    get bucketSize() {
+        return this._bucketSize;
+    }
+    _bucketFirst = 0;
+    /**
+     * The function returns the value of the protected variable `_bucketFirst`.
+     * @returns The value of the `_bucketFirst` property.
+     */
+    get bucketFirst() {
+        return this._bucketFirst;
+    }
+    _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() {
+        return this._firstInBucket;
+    }
+    _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() {
+        return this._bucketLast;
+    }
+    _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() {
+        return this._lastInBucket;
+    }
+    _bucketCount = 0;
+    /**
+     * The function returns the number of buckets.
+     * @returns The number of buckets.
+     */
+    get bucketCount() {
+        return this._bucketCount;
+    }
     _buckets = [];
+    /**
+     * The buckets function returns the buckets property of the object.
+     * @return The buckets property
+     */
     get buckets() {
         return this._buckets;
     }
     _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;
     }
@@ -63,6 +127,10 @@ export class Deque extends IterableElementBase {
             return;
         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() {
         if (this.size === 0)
             return;
@@ -201,13 +269,27 @@ export class Deque extends IterableElementBase {
         return element;
     }
     /**
-     * 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() {
         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.
      */
@@ -223,7 +305,7 @@ export class Deque extends IterableElementBase {
     *begin() {
         let index = 0;
         while (index < this.size) {
-            yield this.getAt(index);
+            yield this.at(index);
             index++;
         }
     }
@@ -234,7 +316,7 @@ export class Deque extends IterableElementBase {
     *reverseBegin() {
         let index = this.size - 1;
         while (index >= 0) {
-            yield this.getAt(index);
+            yield this.at(index);
             index--;
         }
     }
@@ -246,13 +328,13 @@ export class Deque extends IterableElementBase {
      * 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) {
+    at(pos) {
         rangeCheck(pos, 0, this.size - 1);
         const { bucketIndex, indexInBucket } = this._getBucketAndPosition(pos);
         return this._buckets[bucketIndex][indexInBucket];
@@ -310,9 +392,9 @@ export class Deque extends IterableElementBase {
         else {
             const arr = [];
             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)
@@ -332,26 +414,75 @@ export class Deque extends IterableElementBase {
      * 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) {
-        if (pos < 0) {
-            this.clear();
-            return 0;
+    cut(pos, isCutSelf = false) {
+        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([], { 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, isCutSelf = false) {
+        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([], { 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.
@@ -400,14 +531,14 @@ export class Deque extends IterableElementBase {
         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;
     }
     /**
@@ -451,15 +582,15 @@ export class Deque extends IterableElementBase {
             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;
     }
     /**
@@ -479,7 +610,7 @@ export class Deque extends IterableElementBase {
     sort(comparator) {
         const arr = [];
         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) {
@@ -523,30 +654,6 @@ export class Deque extends IterableElementBase {
         this._bucketLast = newBuckets.length - 1;
         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) {
-        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)
@@ -564,7 +671,7 @@ export class Deque extends IterableElementBase {
      */
     indexOf(element) {
         for (let i = 0; i < this.size; ++i) {
-            if (this.getAt(i) === element) {
+            if (this.at(i) === element) {
                 return i;
             }
         }
@@ -584,6 +691,22 @@ export class Deque extends IterableElementBase {
     toArray() {
         return [...this];
     }
+    /**
+     * 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() {
+        return new Deque([...this], { bucketSize: this.bucketSize });
+    }
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -646,8 +769,8 @@ export class Deque extends IterableElementBase {
      * Space Complexity: O(n) - Due to potential resizing.
      */
     /**
-     * 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
@@ -657,12 +780,12 @@ export class Deque extends IterableElementBase {
         return this.push(element);
     }
     /**
-     * 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.
@@ -671,8 +794,13 @@ export class Deque extends IterableElementBase {
         return this.pop();
     }
     /**
-     * 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
@@ -682,8 +810,13 @@ export class Deque extends IterableElementBase {
         return this.unshift(element);
     }
     /**
-     * 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
@@ -693,6 +826,11 @@ export class Deque extends IterableElementBase {
         return this.shift();
     }
     /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     * /
+  
+     /**
      * Time Complexity: O(n)
      * Space Complexity: O(1)
      *
@@ -701,7 +839,7 @@ export class Deque extends IterableElementBase {
      */
     *_getIterator() {
         for (let i = 0; i < this.size; ++i) {
-            yield this.getAt(i);
+            yield this.at(i);
         }
     }
     /**