data-structure-typed 1.54.3 → 2.0.1

package/dist/individuals/stack/stack.mjs

@@ -0,0 +1,415 @@
+// src/data-structures/base/iterable-element-base.ts
+var IterableElementBase = class {
+  /**
+   * The protected constructor initializes the options for the IterableElementBase class, including the
+   * toElementFn function.
+   * @param [options] - An optional object that contains the following properties:
+   */
+  constructor(options) {
+    if (options) {
+      const { toElementFn } = options;
+      if (typeof toElementFn === "function") this._toElementFn = toElementFn;
+      else if (toElementFn) throw new TypeError("toElementFn must be a function type");
+    }
+  }
+  _toElementFn;
+  get toElementFn() {
+    return this._toElementFn;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function is an implementation of the Symbol.iterator method that returns an IterableIterator.
+   * @param {any[]} args - The `args` parameter in the code snippet represents a rest parameter. It
+   * allows the function to accept any number of arguments as an array. In this case, the `args`
+   * parameter is used to pass any number of arguments to the `_getIterator` method.
+   */
+  *[Symbol.iterator](...args) {
+    yield* this._getIterator(...args);
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function returns an iterator that yields all the values in the object.
+   */
+  *values() {
+    for (const item of this) {
+      yield item;
+    }
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `every` function checks if every element in the array satisfies a given predicate.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * the current element being processed, its index, and the array it belongs to. It should return a
+   * boolean value indicating whether the element satisfies a certain condition or not.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
+   * passed as the `this` value to the `predicate` function. If `thisArg` is
+   * @returns The `every` method is returning a boolean value. It returns `true` if every element in
+   * the array satisfies the provided predicate function, and `false` otherwise.
+   */
+  every(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (!predicate.call(thisArg, item, index++, this)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The "some" function checks if at least one element in a collection satisfies a given predicate.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * `value`, `index`, and `array`. It should return a boolean value indicating whether the current
+   * element satisfies the condition.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
+   * it will be passed as the `this` value to the `predicate` function. If `thisArg
+   * @returns a boolean value. It returns true if the predicate function returns true for any element
+   * in the collection, and false otherwise.
+   */
+  some(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (predicate.call(thisArg, item, index++, this)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `forEach` function iterates over each element in an array-like object and calls a callback
+   * function for each element.
+   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
+   * the array. It takes three arguments: the current element being processed, the index of the current
+   * element, and the array that forEach was called upon.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
+   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   */
+  forEach(callbackfn, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      callbackfn.call(thisArg, item, index++, this);
+    }
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `find` function iterates over the elements of an array-like object and returns the first
+   * element that satisfies the provided callback function.
+   * @param predicate - The predicate parameter is a function that will be called for each element in
+   * the array. It takes three arguments: the current element being processed, the index of the current
+   * element, and the array itself. The function should return a boolean value indicating whether the
+   * current element matches the desired condition.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
+   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   * @returns The `find` method returns the first element in the array that satisfies the provided
+   * callback function. If no element satisfies the callback function, `undefined` is returned.
+   */
+  find(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (predicate.call(thisArg, item, index++, this)) return item;
+    }
+    return;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The function checks if a given element exists in a collection.
+   * @param {E} element - The parameter "element" is of type E, which means it can be any type. It
+   * represents the element that we want to check for existence in the collection.
+   * @returns a boolean value. It returns true if the element is found in the collection, and false
+   * otherwise.
+   */
+  has(element) {
+    for (const ele of this) {
+      if (ele === element) return true;
+    }
+    return false;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The `reduce` function iterates over the elements of an array-like object and applies a callback
+   * function to reduce them into a single value.
+   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
+   * the array. It takes four arguments:
+   * @param {U} initialValue - The initialValue parameter is the initial value of the accumulator. It
+   * is the value that the accumulator starts with before the reduction operation begins.
+   * @returns The `reduce` method is returning the final value of the accumulator after iterating over
+   * all the elements in the array and applying the callback function to each element.
+   */
+  reduce(callbackfn, initialValue) {
+    let accumulator = initialValue ?? 0;
+    let index = 0;
+    for (const item of this) {
+      accumulator = callbackfn(accumulator, item, index++, this);
+    }
+    return accumulator;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `toArray` function converts a linked list into an array.
+   * @returns The `toArray()` method is returning an array of type `E[]`.
+   */
+  toArray() {
+    return [...this];
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The print function logs the elements of an array to the console.
+   */
+  toVisual() {
+    return [...this];
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The print function logs the elements of an array to the console.
+   */
+  print() {
+    console.log(this.toVisual());
+  }
+};
+
+// src/data-structures/stack/stack.ts
+var Stack = class _Stack extends IterableElementBase {
+  constructor(elements = [], options) {
+    super(options);
+    this.pushMany(elements);
+  }
+  _elements = [];
+  /**
+   * The elements function returns the elements of this set.
+   * @return An array of elements
+   */
+  get elements() {
+    return this._elements;
+  }
+  /**
+   * The size() function returns the number of elements in an array.
+   * @returns The size of the elements array.
+   */
+  get size() {
+    return this.elements.length;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The function "fromArray" creates a new Stack object from an array of elements.
+   * @param {E[]} elements - The `elements` parameter is an array of elements of type `E`.
+   * @returns {Stack} The method is returning a new instance of the Stack class, initialized with the elements from the input
+   * array.
+   */
+  static fromArray(elements) {
+    return new _Stack(elements);
+  }
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The function checks if an array is empty and returns a boolean value.
+   * @returns A boolean value indicating whether the `_elements` array is empty or not.
+   */
+  isEmpty() {
+    return this.elements.length === 0;
+  }
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `peek` function returns the last element of an array, or undefined if the array is empty.
+   * @returns The `peek()` function returns the last element of the `_elements` array, or `undefined` if the array is empty.
+   */
+  peek() {
+    if (this.isEmpty()) return void 0;
+    return this.elements[this.elements.length - 1];
+  }
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The push function adds an element to the stack and returns the updated stack.
+   * @param {E} element - The parameter "element" is of type E, which means it can be any data type.
+   * @returns The `push` method is returning the updated `Stack<E>` object.
+   */
+  push(element) {
+    this.elements.push(element);
+    return true;
+  }
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The `pop` function removes and returns the last element from an array, or returns undefined if the array is empty.
+   * @returns The `pop()` method is returning the last element of the array `_elements` if the array is not empty. If the
+   * array is empty, it returns `undefined`.
+   */
+  pop() {
+    if (this.isEmpty()) return;
+    return this.elements.pop();
+  }
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(1)
+   *
+   * The function `pushMany` iterates over elements and pushes them into an array after applying a
+   * transformation function if provided.
+   * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the `pushMany` function
+   * is an iterable containing elements of type `E` or `R`. The function iterates over each element in
+   * the iterable and pushes it into the data structure. If a transformation function `toElementFn` is
+   * provided, it is used to
+   * @returns The `pushMany` function is returning an array of boolean values indicating whether each
+   * element was successfully pushed into the data structure.
+   */
+  pushMany(elements) {
+    const ans = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.push(this.toElementFn(el)));
+      } else {
+        ans.push(this.push(el));
+      }
+    }
+    return ans;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The toArray function returns a copy of the elements in an array.
+   * @returns An array of type E.
+   */
+  delete(element) {
+    const index = this.elements.indexOf(element);
+    return this.deleteAt(index);
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   * The toArray function returns a copy of the elements in an array.
+   * @returns An array of type E.
+   */
+  deleteAt(index) {
+    const spliced = this.elements.splice(index, 1);
+    return spliced.length === 1;
+  }
+  /**
+   * Time Complexity: O(1)
+   * Space Complexity: O(1)
+   *
+   * The clear function clears the elements array.
+   */
+  clear() {
+    this._elements = [];
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `clone()` function returns a new `Stack` object with the same elements as the original stack.
+   * @returns The `clone()` method is returning a new `Stack` object with a copy of the `_elements` array.
+   */
+  clone() {
+    return new _Stack(this, { toElementFn: this.toElementFn });
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `filter` function creates a new stack containing elements from the original stack that satisfy
+   * a given predicate function.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * the current element being iterated over, the index of the current element, and the stack itself.
+   * It should return a boolean value indicating whether the element should be included in the filtered
+   * stack or not.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
+   * passed as the `this` value to the `predicate` function. If `thisArg` is
+   * @returns The `filter` method is returning a new `Stack` object that contains the elements that
+   * satisfy the given predicate function.
+   */
+  filter(predicate, thisArg) {
+    const newStack = new _Stack([], { toElementFn: this.toElementFn });
+    let index = 0;
+    for (const el of this) {
+      if (predicate.call(thisArg, el, index, this)) {
+        newStack.push(el);
+      }
+      index++;
+    }
+    return newStack;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `map` function takes a callback function and applies it to each element in the stack,
+   * returning a new stack with the results.
+   * @param callback - The callback parameter is a function that will be called for each element in the
+   * stack. It takes three arguments: the current element, the index of the element, and the stack
+   * itself. It should return a new value that will be added to the new stack.
+   * @param [toElementFn] - The `toElementFn` parameter is an optional function that can be used to
+   * transform the raw element (`RM`) into a new element (`EM`) before pushing it into the new stack.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
+   * specify the value of `this` within the callback function. It is used to set the context or scope
+   * in which the callback function will be executed. If `thisArg` is provided, it will be used as the
+   * value of
+   * @returns a new Stack object with elements of type EM and raw elements of type RM.
+   */
+  map(callback, toElementFn, thisArg) {
+    const newStack = new _Stack([], { toElementFn });
+    let index = 0;
+    for (const el of this) {
+      newStack.push(callback.call(thisArg, el, index, this));
+      index++;
+    }
+    return newStack;
+  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * Custom iterator for the Stack class.
+   * @returns An iterator object.
+   */
+  *_getIterator() {
+    for (let i = 0; i < this.elements.length; i++) {
+      yield this.elements[i];
+    }
+  }
+};
+export {
+  Stack
+};
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */