binary-tree-typed 2.4.5 → 2.5.1

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

@@ -11,6 +11,89 @@ import { ERR } from '../../common';
 /**
  *
  */
+/**
+ * Matrix — a numeric matrix with standard linear algebra operations.
+ *
+ * @example
+ * // Basic matrix arithmetic
+ *  const a = new Matrix([
+ *       [1, 2],
+ *       [3, 4]
+ *     ]);
+ *     const b = new Matrix([
+ *       [5, 6],
+ *       [7, 8]
+ *     ]);
+ *
+ *     const sum = a.add(b);
+ *     console.log(sum?.data); // [
+ *  //      [6, 8],
+ *  //      [10, 12]
+ *  //    ];
+ *
+ *     const diff = b.subtract(a);
+ *     console.log(diff?.data); // [
+ *  //      [4, 4],
+ *  //      [4, 4]
+ *  //    ];
+ * @example
+ * // Matrix multiplication for transformations
+ *  // 2x3 matrix * 3x2 matrix = 2x2 matrix
+ *     const a = new Matrix([
+ *       [1, 2, 3],
+ *       [4, 5, 6]
+ *     ]);
+ *     const b = new Matrix([
+ *       [7, 8],
+ *       [9, 10],
+ *       [11, 12]
+ *     ]);
+ *
+ *     const product = a.multiply(b);
+ *     console.log(product?.rows); // 2;
+ *     console.log(product?.cols); // 2;
+ *     // Row 0: 1*7+2*9+3*11=58, 1*8+2*10+3*12=64
+ *     // Row 1: 4*7+5*9+6*11=139, 4*8+5*10+6*12=154
+ *     console.log(product?.data); // [
+ *  //      [58, 64],
+ *  //      [139, 154]
+ *  //    ];
+ * @example
+ * // Matrix transpose (square matrix)
+ *  const m = new Matrix([
+ *       [1, 2, 3],
+ *       [4, 5, 6],
+ *       [7, 8, 9]
+ *     ]);
+ *
+ *     const transposed = m.transpose();
+ *     console.log(transposed.rows); // 3;
+ *     console.log(transposed.cols); // 3;
+ *     console.log(transposed.data); // [
+ *  //      [1, 4, 7],
+ *  //      [2, 5, 8],
+ *  //      [3, 6, 9]
+ *  //    ];
+ *
+ *     // Transpose of transpose = original
+ *     console.log(transposed.transpose().data); // m.data;
+ * @example
+ * // Get and set individual cells
+ *  const m = new Matrix([
+ *       [0, 0, 0],
+ *       [0, 0, 0]
+ *     ]);
+ *
+ *     m.set(0, 1, 42);
+ *     m.set(1, 2, 99);
+ *
+ *     console.log(m.get(0, 1)); // 42;
+ *     console.log(m.get(1, 2)); // 99;
+ *     console.log(m.get(0, 0)); // 0;
+ *
+ *     // Out of bounds returns undefined
+ *     console.log(m.get(5, 5)); // undefined;
+ */
 export class Matrix {
   /**
    * The constructor function initializes a matrix object with the provided data and options, or with
@@ -106,6 +189,54 @@ export class Matrix {
    * retrieve from the data array.
    * @returns The `get` function returns a number if the provided row and column indices are valid.
    * Otherwise, it returns `undefined`.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Get and set individual cells
+ *  const m = new Matrix([
+ *       [0, 0, 0],
+ *       [0, 0, 0]
+ *     ]);
+ *
+ *     m.set(0, 1, 42);
+ *     m.set(1, 2, 99);
+ *
+ *     console.log(m.get(0, 1)); // 42;
+ *     console.log(m.get(1, 2)); // 99;
+ *     console.log(m.get(0, 0)); // 0;
+ *
+ *     // Out of bounds returns undefined
+ *     console.log(m.get(5, 5)); // undefined;
    */
   get(row: number, col: number): number | undefined {
     if (this.isValidIndex(row, col)) {
@@ -124,6 +255,45 @@ export class Matrix {
    * @returns a boolean value. It returns true if the index (row, col) is valid and the value is
    * successfully set in the data array. It returns false if the index is invalid and the value is not
    * set.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Modify individual cells
+ *  const m = Matrix.zeros(2, 2);
+ *     console.log(m.set(0, 0, 5)); // true;
+ *     console.log(m.set(1, 1, 10)); // true;
+ *     console.log(m.get(0, 0)); // 5;
+ *     console.log(m.get(1, 1)); // 10;
    */
   set(row: number, col: number, value: number): boolean {
     if (this.isValidIndex(row, col)) {
@@ -148,6 +318,60 @@ export class Matrix {
    * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class.
    * @returns The `add` method returns a new `Matrix` object that represents the result of adding the
    * current matrix with the provided `matrix` parameter.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Basic matrix arithmetic
+ *  const a = new Matrix([
+ *       [1, 2],
+ *       [3, 4]
+ *     ]);
+ *     const b = new Matrix([
+ *       [5, 6],
+ *       [7, 8]
+ *     ]);
+ *
+ *     const sum = a.add(b);
+ *     console.log(sum?.data); // [
+ *  //      [6, 8],
+ *  //      [10, 12]
+ *  //    ];
+ *
+ *     const diff = b.subtract(a);
+ *     console.log(diff?.data); // [
+ *  //      [4, 4],
+ *  //      [4, 4]
+ *  //    ];
    */
   add(matrix: Matrix): Matrix | undefined {
     if (!this.isMatchForCalculate(matrix)) {
@@ -161,10 +385,7 @@ export class Matrix {
         const a = this.get(i, j),
           b = matrix.get(i, j);
         if (a !== undefined && b !== undefined) {
-          const added = this._addFn(a, b);
-          if (added) {
-            resultData[i][j] = added;
-          }
+          resultData[i][j] = this._addFn(a, b) ?? 0;
         }
       }
     }
@@ -184,6 +405,44 @@ export class Matrix {
    * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class. It
    * represents the matrix that you want to subtract from the current matrix.
    * @returns a new Matrix object with the result of the subtraction operation.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Element-wise subtraction
+ *  const a = Matrix.from([[5, 6], [7, 8]]);
+ *     const b = Matrix.from([[1, 2], [3, 4]]);
+ *     const result = a.subtract(b);
+ *     console.log(result?.toArray()); // [[4, 4], [4, 4]];
    */
   subtract(matrix: Matrix): Matrix | undefined {
     if (!this.isMatchForCalculate(matrix)) {
@@ -197,10 +456,7 @@ export class Matrix {
         const a = this.get(i, j),
           b = matrix.get(i, j);
         if (a !== undefined && b !== undefined) {
-          const subtracted = this._subtractFn(a, b);
-          if (subtracted) {
-            resultData[i][j] = subtracted;
-          }
+          resultData[i][j] = this._subtractFn(a, b) ?? 0;
         }
       }
     }
@@ -219,6 +475,60 @@ export class Matrix {
    * as a new matrix.
    * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class.
    * @returns a new Matrix object.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Matrix multiplication for transformations
+ *  // 2x3 matrix * 3x2 matrix = 2x2 matrix
+ *     const a = new Matrix([
+ *       [1, 2, 3],
+ *       [4, 5, 6]
+ *     ]);
+ *     const b = new Matrix([
+ *       [7, 8],
+ *       [9, 10],
+ *       [11, 12]
+ *     ]);
+ *
+ *     const product = a.multiply(b);
+ *     console.log(product?.rows); // 2;
+ *     console.log(product?.cols); // 2;
+ *     // Row 0: 1*7+2*9+3*11=58, 1*8+2*10+3*12=64
+ *     // Row 1: 4*7+5*9+6*11=139, 4*8+5*10+6*12=154
+ *     console.log(product?.data); // [
+ *  //      [58, 64],
+ *  //      [139, 154]
+ *  //    ];
    */
   multiply(matrix: Matrix): Matrix | undefined {
     if (this.cols !== matrix.rows) {
@@ -257,9 +567,60 @@ export class Matrix {
    * The transpose function takes a matrix and returns a new matrix that is the transpose of the
    * original matrix.
    * @returns The transpose() function returns a new Matrix object with the transposed data.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Matrix transpose (square matrix)
+ *  const m = new Matrix([
+ *       [1, 2, 3],
+ *       [4, 5, 6],
+ *       [7, 8, 9]
+ *     ]);
+ *
+ *     const transposed = m.transpose();
+ *     console.log(transposed.rows); // 3;
+ *     console.log(transposed.cols); // 3;
+ *     console.log(transposed.data); // [
+ *  //      [1, 4, 7],
+ *  //      [2, 5, 8],
+ *  //      [3, 6, 9]
+ *  //    ];
+ *
+ *     // Transpose of transpose = original
+ *     console.log(transposed.transpose().data); // m.data;
    */
   transpose(): Matrix {
-    if (this.data.some(row => row.length !== this.rows)) {
+    if (this.data.some(row => row.length !== this.cols)) {
       throw new Error(ERR.matrixNotRectangular());
     }
 
@@ -285,6 +646,49 @@ export class Matrix {
   /**
    * The `inverse` function calculates the inverse of a square matrix using Gaussian elimination.
    * @returns a Matrix object, which represents the inverse of the original matrix.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Compute the inverse of a 2x2 matrix
+ *  const m = Matrix.from([[4, 7], [2, 6]]);
+ *     const inv = m.inverse();
+ *     console.log(inv); // defined;
+ *     // A * A^-1 should ≈ Identity
+ *     const product = m.multiply(inv!);
+ *     console.log(product?.get(0, 0)); // toBeCloseTo;
+ *     console.log(product?.get(0, 1)); // toBeCloseTo;
+ *     console.log(product?.get(1, 0)); // toBeCloseTo;
+ *     console.log(product?.get(1, 1)); // toBeCloseTo;
    */
   inverse(): Matrix | undefined {
     // Check if the matrix is square
@@ -365,6 +769,44 @@ export class Matrix {
    * The dot function calculates the dot product of two matrices and returns a new matrix.
    * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class.
    * @returns a new Matrix object.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Dot product of two matrices
+ *  const a = Matrix.from([[1, 2], [3, 4]]);
+ *     const b = Matrix.from([[5, 6], [7, 8]]);
+ *     const result = a.dot(b);
+ *     console.log(result?.toArray()); // [[19, 22], [43, 50]];
    */
   dot(matrix: Matrix): Matrix | undefined {
     if (this.cols !== matrix.rows) {
@@ -418,15 +860,145 @@ export class Matrix {
    * and properties as the current instance.
    */
   clone(): Matrix {
-    return new Matrix(this.data, {
-      rows: this.rows,
-      cols: this.cols,
+    return new Matrix(
+      this._data.map(row => [...row]),
+      {
+        rows: this.rows,
+        cols: this.cols,
+        addFn: this.addFn,
+        subtractFn: this.subtractFn,
+        multiplyFn: this.multiplyFn
+      }
+    );
+  }
+
+  // ─── Standard interface ─────────────────────────────────────
+
+  /**
+   * Returns [rows, cols] dimensions tuple.
+   */
+  get size(): [number, number] {
+    return [this._rows, this._cols];
+  }
+
+  isEmpty(): boolean {
+    return this._rows === 0 || this._cols === 0;
+  }
+
+  /**
+   * Returns a deep copy of the data as a plain 2D array.
+   */
+  toArray(): number[][] {
+    return this._data.map(row => [...row]);
+  }
+
+  /**
+   * Returns a flat row-major array.
+   */
+  flatten(): number[] {
+    const result: number[] = [];
+    for (const row of this._data) {
+      for (const v of row) result.push(v);
+    }
+    return result;
+  }
+
+  /**
+   * Iterates over rows.
+   */
+  [Symbol.iterator](): IterableIterator<number[]> {
+    const data = this._data;
+    let i = 0;
+    return {
+      [Symbol.iterator]() {
+        return this;
+      },
+      next(): IteratorResult<number[]> {
+        if (i < data.length) {
+          return { value: [...data[i++]], done: false };
+        }
+        return { value: undefined, done: true } as IteratorResult<number[]>;
+      }
+    };
+  }
+
+  /**
+   * Visits each element with its row and column index.
+   */
+  forEach(callback: (value: number, row: number, col: number) => void): void {
+    for (let i = 0; i < this._rows; i++) {
+      for (let j = 0; j < this._cols; j++) {
+        callback(this._data[i][j], i, j);
+      }
+    }
+  }
+
+  /**
+   * Maps each element (number → number) and returns a new Matrix.
+   */
+  map(callback: (value: number, row: number, col: number) => number): Matrix {
+    const resultData: number[][] = [];
+    for (let i = 0; i < this._rows; i++) {
+      resultData[i] = [];
+      for (let j = 0; j < this._cols; j++) {
+        resultData[i][j] = callback(this._data[i][j], i, j);
+      }
+    }
+    return new Matrix(resultData, {
+      rows: this._rows,
+      cols: this._cols,
       addFn: this.addFn,
       subtractFn: this.subtractFn,
       multiplyFn: this.multiplyFn
     });
   }
 
+  print(): void {
+    for (const row of this._data) {
+      console.log(row.join('\t'));
+    }
+  }
+
+  // ─── Factory methods ────────────────────────────────────────
+
+  /**
+   * Creates a rows×cols zero matrix.
+   * @example
+   * ```ts
+   * const z = Matrix.zeros(2, 3); // [[0,0,0],[0,0,0]]
+   * ```
+   */
+  static zeros(rows: number, cols: number): Matrix {
+    const data: number[][] = Array.from({ length: rows }, () => new Array(cols).fill(0));
+    return new Matrix(data);
+  }
+
+  /**
+   * Creates an n×n identity matrix.
+   * @example
+   * ```ts
+   * const I = Matrix.identity(3); // [[1,0,0],[0,1,0],[0,0,1]]
+   * ```
+   */
+  static identity(n: number): Matrix {
+    const data: number[][] = Array.from({ length: n }, (_, i) =>
+      Array.from({ length: n }, (_, j) => (i === j ? 1 : 0))
+    );
+    return new Matrix(data);
+  }
+
+  /**
+   * Creates a Matrix from a plain 2D array (deep copy).
+   * @example
+   * ```ts
+   * const m = Matrix.from([[1, 2], [3, 4]]);
+   * m.get(0, 1); // 2
+   * ```
+   */
+  static from(data: number[][]): Matrix {
+    return new Matrix(data.map(row => [...row]));
+  }
+
   protected _addFn(a: number | undefined, b: number): number | undefined {
     if (a === undefined) return b;
     return a + b;