max-priority-queue-typed 2.4.5 → 2.5.1

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

@@ -21,38 +21,6 @@ import { IterableElementBase } from '../base';
  * 5. Expression Evaluation: Used for the evaluation of arithmetic or logical expressions, especially when dealing with parenthesis matching and operator precedence.
  * 6. Backtracking Algorithms: In problems where multiple branches need to be explored but only one branch can be explored at a time, stacks can be used to save the state at each branching point.
  * @example
- * // basic Stack creation and push operation
- *  // Create a simple Stack with initial values
- *     const stack = new Stack([1, 2, 3, 4, 5]);
- *
- *     // Verify the stack maintains insertion order (LIFO will be shown in pop)
- *     console.log([...stack]); // [1, 2, 3, 4, 5];
- *
- *     // Check length
- *     console.log(stack.size); // 5;
- *
- *     // Push a new element to the top
- *     stack.push(6);
- *     console.log(stack.size); // 6;
- * @example
- * // Stack pop operation (LIFO - Last In First Out)
- *  const stack = new Stack<number>([10, 20, 30, 40, 50]);
- *
- *     // Peek at the top element without removing
- *     const top = stack.peek();
- *     console.log(top); // 50;
- *
- *     // Pop removes from the top (LIFO order)
- *     const popped = stack.pop();
- *     console.log(popped); // 50;
- *
- *     // Next pop gets the previous element
- *     const next = stack.pop();
- *     console.log(next); // 40;
- *
- *     // Verify length decreased
- *     console.log(stack.size); // 3;
- * @example
  * // Function Call Stack
  *  const functionStack = new Stack<string>();
  *     functionStack.push('main');
@@ -159,6 +127,10 @@ import { IterableElementBase } from '../base';
  *       else if (segment && segment !== '.') stack.push(segment);
  *     });
  *     console.log(stack.elements.join('/')); // 'c';
+ * @example
+ * // Convert stack to array
+ *  const stack = new Stack<number>([1, 2, 3]);
+ *     console.log(stack.toArray()); // [1, 2, 3];
  */
 export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
   protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
@@ -192,6 +164,40 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * Get the number of stored elements.
    * @remarks Time O(1), Space O(1)
    * @returns Current size.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get number of elements
+ *  const stack = new Stack<number>([1, 2, 3]);
+ *     console.log(stack.size); // 3;
    */
 
   get size(): number {
@@ -221,6 +227,44 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * Check whether the stack is empty.
    * @remarks Time O(1), Space O(1)
    * @returns True if size is 0.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check if stack has elements
+ *  const stack = new Stack<number>();
+ *     console.log(stack.isEmpty()); // true;
+ *     stack.push(1);
+ *     console.log(stack.isEmpty()); // false;
    */
 
   isEmpty(): boolean {
@@ -231,6 +275,43 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * Get the top element without removing it.
    * @remarks Time O(1), Space O(1)
    * @returns Top element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // View the top element without removing it
+ *  const stack = new Stack<string>(['a', 'b', 'c']);
+ *     console.log(stack.peek()); // 'c';
+ *     console.log(stack.size); // 3;
    */
 
   peek(): E | undefined {
@@ -242,6 +323,52 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * @remarks Time O(1), Space O(1)
    * @param element - Element to push.
    * @returns True when pushed.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // basic Stack creation and push operation
+ *  // Create a simple Stack with initial values
+ *     const stack = new Stack([1, 2, 3, 4, 5]);
+ *
+ *     // Verify the stack maintains insertion order (LIFO will be shown in pop)
+ *     console.log([...stack]); // [1, 2, 3, 4, 5];
+ *
+ *     // Check length
+ *     console.log(stack.size); // 5;
+ *
+ *     // Push a new element to the top
+ *     stack.push(6);
+ *     console.log(stack.size); // 6;
    */
 
   push(element: E): boolean {
@@ -253,6 +380,56 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * Pop and return the top element.
    * @remarks Time O(1), Space O(1)
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Stack pop operation (LIFO - Last In First Out)
+ *  const stack = new Stack<number>([10, 20, 30, 40, 50]);
+ *
+ *     // Peek at the top element without removing
+ *     const top = stack.peek();
+ *     console.log(top); // 50;
+ *
+ *     // Pop removes from the top (LIFO order)
+ *     const popped = stack.pop();
+ *     console.log(popped); // 50;
+ *
+ *     // Next pop gets the previous element
+ *     const next = stack.pop();
+ *     console.log(next); // 40;
+ *
+ *     // Verify length decreased
+ *     console.log(stack.size); // 3;
    */
 
   pop(): E | undefined {
@@ -280,6 +457,40 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * @remarks Time O(N), Space O(1)
    * @param element - Element to remove (using the configured equality).
    * @returns True if an element was removed.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove element
+ *  const stack = new Stack<number>([1, 2, 3]);
+ *     stack.delete(2);
+ *     console.log(stack.toArray()); // [1, 3];
    */
 
   delete(element: E): boolean {
@@ -321,6 +532,41 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * Remove all elements and reset storage.
    * @remarks Time O(1), Space O(1)
    * @returns void
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all elements
+ *  const stack = new Stack<number>([1, 2, 3]);
+ *     stack.clear();
+ *     console.log(stack.isEmpty()); // true;
    */
 
   clear(): void {
@@ -331,6 +577,43 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * Deep clone this stack.
    * @remarks Time O(N), Space O(N)
    * @returns A new stack with the same content.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Create independent copy
+ *  const stack = new Stack<number>([1, 2, 3]);
+ *     const copy = stack.clone();
+ *     copy.pop();
+ *     console.log(stack.size); // 3;
+ *     console.log(copy.size); // 2;
    */
 
   clone(): this {
@@ -345,6 +628,41 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * @param predicate - Predicate (value, index, stack) → boolean to keep value.
    * @param [thisArg] - Value for `this` inside the predicate.
    * @returns A new stack with kept values.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter elements
+ *  const stack = new Stack<number>([1, 2, 3, 4, 5]);
+ *     const evens = stack.filter(x => x % 2 === 0);
+ *     console.log(evens.toArray()); // [2, 4];
    */
 
   filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this {
@@ -384,6 +702,40 @@ export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
    * @param [options] - Options for the output stack (e.g., toElementFn).
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new Stack with mapped elements.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform elements
+ *  const stack = new Stack<number>([1, 2, 3]);
+ *     const doubled = stack.map(x => x * 2);
+ *     console.log(doubled.toArray()); // [2, 4, 6];
    */
 
   map<EM, RM>(