docs: Added example code for HashMap, Queue, and Stack.

CHANGELOG.md

@@ -8,7 +8,7 @@ All notable changes to this project will be documented in this file.
 - [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 - [`auto-changelog`](https://github.com/CookPete/auto-changelog)
 
-## [v1.54.3](https://github.com/zrwusa/data-structure-typed/compare/v1.51.5...main) (upcoming)
+## [v2.0.0](https://github.com/zrwusa/data-structure-typed/compare/v1.51.5...main) (upcoming)
 
 ### Changes
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "data-structure-typed",
-  "version": "1.54.3",
+  "version": "2.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "data-structure-typed",
-      "version": "1.54.3",
+      "version": "2.0.0",
       "license": "MIT",
       "devDependencies": {
         "@eslint/compat": "^1.2.2",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-structure-typed",
-  "version": "1.54.3",
+  "version": "2.0.0",
   "description": "Javascript Data Structure. Heap, Binary Tree, Red Black Tree, Linked List, Deque, Trie, HashMap, Directed Graph, Undirected Graph, Binary Search Tree(BST), AVL Tree, Priority Queue, Graph, Queue, Tree Multiset, Singly Linked List, Doubly Linked List, Max Heap, Max Priority Queue, Min Heap, Min Priority Queue, Stack. Benchmark compared with C++ STL. API aligned with ES6 and Java.util. Usability is comparable to Python",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

src/data-structures/hash/hash-map.ts

@@ -21,6 +21,52 @@ import { isWeakKey, rangeCheck } from '../../utils';
  * 3. Unique Keys: Keys are unique.
  * If you try to insert another entry with the same key, the new one will replace the old entry.
  * 4. Unordered Collection: HashMap does not guarantee the order of entries, and the order may change over time.
+ * @example
+ * // should maintain insertion order
+ *     const linkedHashMap = new LinkedHashMap<number, string>();
+ *     linkedHashMap.set(1, 'A');
+ *     linkedHashMap.set(2, 'B');
+ *     linkedHashMap.set(3, 'C');
+ *
+ *     const result = Array.from(linkedHashMap);
+ *     console.log(result); // [
+ *  //      [1, 'A'],
+ *  //      [2, 'B'],
+ *  //      [3, 'C']
+ *  //    ]
+ * @example
+ * // fast lookup of values by key
+ *     const hashMap = new HashMap<number, string>();
+ *     hashMap.set(1, 'A');
+ *     hashMap.set(2, 'B');
+ *     hashMap.set(3, 'C');
+ *
+ *     console.log(hashMap.get(1)); // 'A'
+ *     console.log(hashMap.get(2)); // 'B'
+ *     console.log(hashMap.get(3)); // 'C'
+ *     console.log(hashMap.get(99)); // undefined
+ * @example
+ * // remove duplicates when adding multiple entries
+ *     const hashMap = new HashMap<number, string>();
+ *     hashMap.set(1, 'A');
+ *     hashMap.set(2, 'B');
+ *     hashMap.set(1, 'C'); // Update value for key 1
+ *
+ *     console.log(hashMap.size); // 2
+ *     console.log(hashMap.get(1)); // 'C'
+ *     console.log(hashMap.get(2)); // 'B'
+ * @example
+ * // count occurrences of keys
+ *     const data = [1, 2, 1, 3, 2, 1];
+ *
+ *     const countMap = new HashMap<number, number>();
+ *     for (const key of data) {
+ *       countMap.set(key, (countMap.get(key) || 0) + 1);
+ *     }
+ *
+ *     console.log(countMap.get(1)); // 3
+ *     console.log(countMap.get(2)); // 2
+ *     console.log(countMap.get(3)); // 1
  */
 export class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V> {
   /**

src/data-structures/queue/queue.ts

@@ -15,6 +15,53 @@ import { LinearBase } from '../base/linear-base';
  * 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 elements that are to be visited.
  * 7. Real-time Queuing: Like queuing systems in banks or supermarkets.
+ * @example
+ * // Sliding Window using Queue
+ *     const nums = [2, 3, 4, 1, 5];
+ *     const k = 2;
+ *     const queue = new Queue<number>();
+ *
+ *     let maxSum = 0;
+ *     let currentSum = 0;
+ *
+ *     nums.forEach((num, i) => {
+ *       queue.push(num);
+ *       currentSum += num;
+ *
+ *       if (queue.length > k) {
+ *         currentSum -= queue.shift()!;
+ *       }
+ *
+ *       if (queue.length === k) {
+ *         maxSum = Math.max(maxSum, currentSum);
+ *       }
+ *     });
+ *
+ *     console.log(maxSum); // 7
+ * @example
+ * // Breadth-First Search (BFS) using Queue
+ *     const graph: { [key in number]: number[] } = {
+ *       1: [2, 3],
+ *       2: [4, 5],
+ *       3: [],
+ *       4: [],
+ *       5: []
+ *     };
+ *
+ *     const queue = new Queue<number>();
+ *     const visited: number[] = [];
+ *
+ *     queue.push(1);
+ *
+ *     while (!queue.isEmpty()) {
+ *       const node = queue.shift()!;
+ *       if (!visited.includes(node)) {
+ *         visited.push(node);
+ *         graph[node].forEach(neighbor => queue.push(neighbor));
+ *       }
+ *     }
+ *
+ *     console.log(visited); // [1, 2, 3, 4, 5]
  */
 export class Queue<E = any, R = any> extends LinearBase<E, R> {
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: QueueOptions<E, R>) {

test/unit/data-structures/binary-tree/avl-tree.test.ts

@@ -1,4 +1,4 @@
-import { AVLTree, AVLTreeNode, BinaryTreeNode, BSTNode, Range } from '../../../../src';
+import { AVLTree, AVLTreeNode, BinaryTreeNode, BSTNode } from '../../../../src';
 
 describe('AVL Tree Test', () => {
   it('should perform various operations on a AVL Tree', () => {

test/unit/data-structures/binary-tree/red-black-tree.test.ts

@@ -1,4 +1,4 @@
-import { BinaryTreeNode, BSTNode, Range, RedBlackTree, RedBlackTreeNode } from '../../../../src';
+import { BinaryTreeNode, BSTNode, RedBlackTree, RedBlackTreeNode } from '../../../../src';
 import { getRandomInt, getRandomIntArray, magnitude } from '../../../utils';
 import { OrderedMap } from 'js-sdsl';
 

test/unit/data-structures/binary-tree/tree-multi-map.test.ts

@@ -1,4 +1,4 @@
-import { BinaryTreeNode, BSTNode, Range, TreeMultiMap, TreeMultiMapNode } from '../../../../src';
+import { BinaryTreeNode, BSTNode, TreeMultiMap, TreeMultiMapNode } from '../../../../src';
 import { getRandomInt } from '../../../utils';
 
 import { isDebugTest } from '../../../config';

test/unit/data-structures/hash/hash-map.test.ts

@@ -842,3 +842,138 @@ describe('LinkedHashMap', () => {
     });
   });
 });
+
+describe('classic uses', () => {
+  it('@example should maintain insertion order', () => {
+    const linkedHashMap = new LinkedHashMap<number, string>();
+    linkedHashMap.set(1, 'A');
+    linkedHashMap.set(2, 'B');
+    linkedHashMap.set(3, 'C');
+
+    const result = Array.from(linkedHashMap);
+    expect(result).toEqual([
+      [1, 'A'],
+      [2, 'B'],
+      [3, 'C']
+    ]);
+  });
+
+  it('should allow reverse iteration', () => {
+    const linkedHashMap = new LinkedHashMap<number, string>();
+    linkedHashMap.set(1, 'A');
+    linkedHashMap.set(2, 'B');
+    linkedHashMap.set(3, 'C');
+
+    const result = Array.from(linkedHashMap.reverseBegin());
+    expect(result).toEqual([
+      [3, 'C'],
+      [2, 'B'],
+      [1, 'A']
+    ]);
+  });
+
+  it('should allow fast deletion at an index', () => {
+    const linkedHashMap = new LinkedHashMap<number, string>();
+    linkedHashMap.set(1, 'A');
+    linkedHashMap.set(2, 'B');
+    linkedHashMap.set(3, 'C');
+
+    linkedHashMap.deleteAt(1);
+
+    const result = Array.from(linkedHashMap);
+    expect(result).toEqual([
+      [1, 'A'],
+      [3, 'C']
+    ]);
+  });
+
+  it('should filter entries correctly', () => {
+    const linkedHashMap = new LinkedHashMap<number, string>();
+    linkedHashMap.set(1, 'A');
+    linkedHashMap.set(2, 'B');
+    linkedHashMap.set(3, 'C');
+
+    const filteredMap = linkedHashMap.filter((key, value) => value !== 'B');
+
+    const result = Array.from(filteredMap);
+    expect(result).toEqual([
+      [1, 'A'],
+      [3, 'C']
+    ]);
+  });
+
+  it('should map entries to a new LinkedHashMap', () => {
+    const linkedHashMap = new LinkedHashMap<number, string>();
+    linkedHashMap.set(1, 'A');
+    linkedHashMap.set(2, 'B');
+
+    const mappedMap = linkedHashMap.map((key, value) => [value, key]);
+
+    const result = Array.from(mappedMap);
+    expect(result).toEqual([
+      ['A', 1],
+      ['B', 2]
+    ]);
+  });
+});
+
+describe('classic uses', () => {
+  it('@example fast lookup of values by key', () => {
+    const hashMap = new HashMap<number, string>();
+    hashMap.set(1, 'A');
+    hashMap.set(2, 'B');
+    hashMap.set(3, 'C');
+
+    expect(hashMap.get(1)).toBe('A');
+    expect(hashMap.get(2)).toBe('B');
+    expect(hashMap.get(3)).toBe('C');
+    expect(hashMap.get(99)).toBeUndefined(); // Key not present
+  });
+
+  it('@example remove duplicates when adding multiple entries', () => {
+    const hashMap = new HashMap<number, string>();
+    hashMap.set(1, 'A');
+    hashMap.set(2, 'B');
+    hashMap.set(1, 'C'); // Update value for key 1
+
+    expect(hashMap.size).toBe(2);
+    expect(hashMap.get(1)).toBe('C');
+    expect(hashMap.get(2)).toBe('B');
+  });
+
+  it('@example count occurrences of keys', () => {
+    const data = [1, 2, 1, 3, 2, 1];
+
+    const countMap = new HashMap<number, number>();
+    for (const key of data) {
+      countMap.set(key, (countMap.get(key) || 0) + 1);
+    }
+
+    expect(countMap.get(1)).toBe(3);
+    expect(countMap.get(2)).toBe(2);
+    expect(countMap.get(3)).toBe(1);
+  });
+
+  it('should group entries by a key-derived property', () => {
+    const entries = [
+      { id: 1, group: 'A' },
+      { id: 2, group: 'B' },
+      { id: 3, group: 'A' },
+      { id: 4, group: 'B' }
+    ];
+
+    const groupedMap = new HashMap<string, number[]>();
+
+    for (const entry of entries) {
+      const group = entry.group;
+      const id = entry.id;
+      if (!groupedMap.has(group)) {
+        groupedMap.set(group, []);
+      }
+      groupedMap.get(group)?.push(id);
+    }
+
+    expect(groupedMap.get('A')).toEqual([1, 3]);
+    expect(groupedMap.get('B')).toEqual([2, 4]);
+  });
+});

test/unit/data-structures/queue/queue.test.ts

@@ -454,3 +454,217 @@ describe('LinkedListQueue', () => {
     expect(cloned.length).toBe(2);
   });
 });
+
+describe('Queue', () => {
+  // Test queue initialization
+  it('should initialize correctly with no elements', () => {
+    const queue = new Queue();
+    expect(queue.isEmpty()).toBe(true);
+    expect(queue.length).toBe(0);
+    expect(queue.first).toBeUndefined();
+    expect(queue.last).toBeUndefined();
+  });
+
+  it('should initialize correctly with given elements', () => {
+    const queue = new Queue([1, 2, 3]);
+    expect(queue.length).toBe(3);
+    expect(queue.first).toBe(1);
+    expect(queue.last).toBe(3);
+  });
+
+  // Test push and pushMany
+  it('should add elements to the queue', () => {
+    const queue = new Queue<number>();
+    queue.push(1);
+    queue.push(2);
+    expect(queue.length).toBe(2);
+    expect(queue.first).toBe(1);
+    expect(queue.last).toBe(2);
+  });
+
+  it('should add multiple elements using pushMany', () => {
+    const queue = new Queue<number>();
+    queue.pushMany([1, 2, 3]);
+    expect(queue.length).toBe(3);
+    expect(queue.elements).toEqual([1, 2, 3]);
+  });
+
+  // Test shift
+  it('should remove the first element from the queue', () => {
+    const queue = new Queue([1, 2, 3]);
+    const shifted = queue.shift();
+    expect(shifted).toBe(1);
+    expect(queue.length).toBe(2);
+    expect(queue.first).toBe(2);
+  });
+
+  // Test delete and deleteAt
+  it('should delete an element from the queue', () => {
+    const queue = new Queue([1, 2, 3]);
+    const result = queue.delete(2);
+    expect(result).toBe(true);
+    expect(queue.elements).toEqual([1, 3]);
+  });
+
+  it('should delete an element at a specific index', () => {
+    const queue = new Queue([1, 2, 3]);
+    const deleted = queue.deleteAt(1);
+    expect(deleted).toBe(2);
+    expect(queue.elements).toEqual([1, 3]);
+  });
+
+  // Test at
+  it('should retrieve an element by index', () => {
+    const queue = new Queue([1, 2, 3]);
+    expect(queue.at(0)).toBe(1);
+    expect(queue.at(2)).toBe(3);
+  });
+
+  // Test reverse
+  it('should reverse the queue', () => {
+    const queue = new Queue([1, 2, 3]);
+    queue.reverse();
+    expect(queue.elements).toEqual([3, 2, 1]);
+    expect(queue.first).toBe(3);
+    expect(queue.last).toBe(1);
+  });
+
+  // Test addAt
+  it('should add an element at a specific index', () => {
+    const queue = new Queue([1, 3]);
+    const result = queue.addAt(1, 2);
+    expect(result).toBe(true);
+    expect(queue.elements).toEqual([1, 2, 3]);
+  });
+
+  // Test setAt
+  it('should set an element at a specific index', () => {
+    const queue = new Queue([1, 2, 3]);
+    const result = queue.setAt(1, 10);
+    expect(result).toBe(true);
+    expect(queue.elements).toEqual([1, 10, 3]);
+  });
+
+  // Test clear
+  it('should clear the queue', () => {
+    const queue = new Queue([1, 2, 3]);
+    queue.clear();
+    expect(queue.isEmpty()).toBe(true);
+    expect(queue.length).toBe(0);
+  });
+
+  // Test compact
+  it('should compact the queue', () => {
+    const queue = new Queue([1, 2, 3]);
+    queue.shift();
+    queue.shift();
+    queue.compact();
+    expect(queue.elements).toEqual([3]);
+  });
+
+  // Test splice
+  it('should splice elements from the queue', () => {
+    const queue = new Queue([1, 2, 3, 4]);
+    const removed = queue.splice(1, 2);
+    expect(removed.elements).toEqual([2, 3]);
+    expect(queue.elements).toEqual([1, 4]);
+  });
+
+  // Test clone
+  it('should create a clone of the queue', () => {
+    const queue = new Queue([1, 2, 3]);
+    const clone = queue.clone();
+    expect(clone.elements).toEqual(queue.elements);
+    clone.push(4);
+    expect(queue.elements).not.toContain(4);
+  });
+
+  // Test filter
+  it('should filter elements based on a predicate', () => {
+    const queue = new Queue([1, 2, 3, 4]);
+    const filtered = queue.filter(el => el % 2 === 0);
+    expect(filtered.elements).toEqual([2, 4]);
+  });
+
+  // Test map
+  it('should map elements to a new queue', () => {
+    const queue = new Queue([1, 2, 3]);
+    const mapped = queue.map(el => el * 2);
+    expect(mapped.elements).toEqual([2, 4, 6]);
+  });
+});
+
+describe('classic uses', () => {
+  it('@example Sliding Window using Queue', () => {
+    const nums = [2, 3, 4, 1, 5];
+    const k = 2;
+    const queue = new Queue<number>();
+
+    let maxSum = 0;
+    let currentSum = 0;
+
+    nums.forEach((num, i) => {
+      queue.push(num);
+      currentSum += num;
+
+      if (queue.length > k) {
+        currentSum -= queue.shift()!;
+      }
+
+      if (queue.length === k) {
+        maxSum = Math.max(maxSum, currentSum);
+      }
+    });
+
+    expect(maxSum).toBe(7); // Maximum sum is from subarray [3, 4].
+  });
+
+  it('@example Breadth-First Search (BFS) using Queue', () => {
+    const graph: { [key in number]: number[] } = {
+      1: [2, 3],
+      2: [4, 5],
+      3: [],
+      4: [],
+      5: []
+    };
+
+    const queue = new Queue<number>();
+    const visited: number[] = [];
+
+    queue.push(1);
+
+    while (!queue.isEmpty()) {
+      const node = queue.shift()!;
+      if (!visited.includes(node)) {
+        visited.push(node);
+        graph[node].forEach(neighbor => queue.push(neighbor));
+      }
+    }
+
+    expect(visited).toEqual([1, 2, 3, 4, 5]); // Expected BFS traversal order.
+  });
+
+  it('Task Scheduling using Queue', () => {
+    const tasks = ['A', 'A', 'A', 'B', 'B', 'B'];
+    const cooldown = 2;
+
+    const taskQueue = new Queue<string>();
+    const cooldownQueue = new Queue<string>();
+
+    for (const task of tasks) {
+      while (!cooldownQueue.isEmpty() && cooldownQueue.first === task) {
+        cooldownQueue.shift();
+        taskQueue.push('idle');
+      }
+
+      taskQueue.push(task);
+      cooldownQueue.push(task);
+      if (cooldownQueue.length > cooldown) {
+        cooldownQueue.shift();
+      }
+    }
+
+    const scheduled = taskQueue.elements;
+    expect(scheduled).toEqual(['A', 'idle', 'A', 'idle', 'A', 'B', 'B', 'idle', 'idle', 'B']);
+  });
+});

test/unit/data-structures/stack/stack.test.ts

@@ -162,3 +162,168 @@ describe('Stack iterative methods', () => {
     }).toThrow('toElementFn must be a function type');
   });
 });
+
+describe('classic uses', () => {
+  it('@example Balanced Parentheses or Brackets', () => {
+    type ValidCharacters = ')' | '(' | ']' | '[' | '}' | '{';
+
+    const stack = new Stack<string>();
+    const input: ValidCharacters[] = '[({})]'.split('') as ValidCharacters[];
+    const matches: { [key in ValidCharacters]?: ValidCharacters } = { ')': '(', ']': '[', '}': '{' };
+    for (const char of input) {
+      if ('([{'.includes(char)) {
+        stack.push(char);
+      } else if (')]}'.includes(char)) {
+        if (stack.pop() !== matches[char]) {
+          fail('Parentheses are not balanced');
+        }
+      }
+    }
+    expect(stack.isEmpty()).toBe(true);
+  });
+
+  it('@example Expression Evaluation and Conversion', () => {
+    const stack = new Stack<number>();
+    const expression = [5, 3, '+']; // Equivalent to 5 + 3
+    expression.forEach(token => {
+      if (typeof token === 'number') {
+        stack.push(token);
+      } else {
+        const b = stack.pop()!;
+        const a = stack.pop()!;
+        stack.push(token === '+' ? a + b : 0); // Only handling '+' here
+      }
+    });
+    expect(stack.pop()).toBe(8);
+  });
+
+  it('@example Depth-First Search (DFS)', () => {
+    const stack = new Stack<number>();
+    const graph: { [key in number]: number[] } = { 1: [2, 3], 2: [4], 3: [5], 4: [], 5: [] };
+    const visited: number[] = [];
+    stack.push(1);
+    while (!stack.isEmpty()) {
+      const node = stack.pop()!;
+      if (!visited.includes(node)) {
+        visited.push(node);
+        graph[node].forEach(neighbor => stack.push(neighbor));
+      }
+    }
+    expect(visited).toEqual([1, 3, 5, 2, 4]); // Example DFS order
+  });
+
+  it('@example Backtracking Algorithms', () => {
+    const stack = new Stack<[number, number]>();
+    const maze = [
+      ['S', ' ', 'X'],
+      ['X', ' ', 'X'],
+      [' ', ' ', 'E']
+    ];
+    const start: [number, number] = [0, 0];
+    const end = [2, 2];
+    const directions = [
+      [0, 1], // To the right
+      [1, 0], // down
+      [0, -1], // left
+      [-1, 0] // up
+    ];
+
+    const visited = new Set<string>(); // Used to record visited nodes
+    stack.push(start);
+    const path: number[][] = [];
+
+    while (!stack.isEmpty()) {
+      const [x, y] = stack.pop()!;
+      if (visited.has(`${x},${y}`)) continue; // Skip already visited nodes
+      visited.add(`${x},${y}`);
+
+      path.push([x, y]);
+
+      if (x === end[0] && y === end[1]) {
+        break; // Find the end point and exit
+      }
+
+      for (const [dx, dy] of directions) {
+        const nx = x + dx;
+        const ny = y + dy;
+        if (
+          maze[nx]?.[ny] === ' ' || // feasible path
+          maze[nx]?.[ny] === 'E' // destination
+        ) {
+          stack.push([nx, ny]);
+        }
+      }
+    }
+
+    expect(path).toContainEqual(end);
+  });
+
+  it('@example Function Call Stack', () => {
+    const functionStack = new Stack<string>();
+    functionStack.push('main');
+    functionStack.push('foo');
+    functionStack.push('bar');
+    expect(functionStack.pop()).toBe('bar');
+    expect(functionStack.pop()).toBe('foo');
+    expect(functionStack.pop()).toBe('main');
+  });
+
+  it('@example Simplify File Paths', () => {
+    const stack = new Stack<string>();
+    const path = '/a/./b/../../c';
+    path.split('/').forEach(segment => {
+      if (segment === '..') stack.pop();
+      else if (segment && segment !== '.') stack.push(segment);
+    });
+    expect(stack.elements.join('/')).toBe('c');
+  });
+
+  it('@example Stock Span Problem', () => {
+    const stack = new Stack<number>();
+    const prices = [100, 80, 60, 70, 60, 75, 85];
+    const spans: number[] = [];
+    prices.forEach((price, i) => {
+      while (!stack.isEmpty() && prices[stack.peek()!] <= price) {
+        stack.pop();
+      }
+      spans.push(stack.isEmpty() ? i + 1 : i - stack.peek()!);
+      stack.push(i);
+    });
+    expect(spans).toEqual([1, 1, 1, 2, 1, 4, 6]);
+  });
+
+  it('Browser Navigation', () => {
+    const backStack = new Stack<string>();
+    const forwardStack = new Stack<string>();
+    backStack.push('Page 1');
+    backStack.push('Page 2');
+    forwardStack.push(backStack.pop()!);
+    expect(backStack.size).toBe(1);
+    expect(forwardStack.size).toBe(1);
+  });
+
+  it('String Reversal', () => {
+    const stack = new Stack<string>();
+    const input = 'hello';
+    const reversed = [];
+    input.split('').forEach(char => stack.push(char));
+    while (!stack.isEmpty()) {
+      reversed.push(stack.pop());
+    }
+    expect(reversed.join('')).toBe('olleh');
+  });
+
+  it('Next Greater Element', () => {
+    const stack = new Stack<number>();
+    const array = [4, 5, 2, 25];
+    const nextGreater = new Array(array.length).fill(-1);
+    array.forEach((_, i) => {
+      while (!stack.isEmpty() && array[stack.peek()!] < array[i]) {
+        const idx = stack.pop()!;
+        nextGreater[idx] = array[i];
+      }
+      stack.push(i);
+    });
+    expect(nextGreater).toEqual([5, 25, 25, -1]);
+  });
+});