feat: add concat to join two matrices along a chosen dimension

[tayal-sarthak]

Closes #54.
Closes #161.

Summary

The library has no way to join two matrices. Both linked issues ask for one, #161 pointing at the numpy stack, hstack, vstack equivalents. The maintainer reply on #54 proposed matrix1.concat(matrix2) returning a new matrix, which is the shape implemented here.

API

concat(other: MaybeMatrix, by?: MatrixDimension): Matrix;

• by === 'row', the default, stacks the two matrices vertically. Both operands need the same number of columns. The result has this.rows + other.rows rows.
• by === 'column' stacks them side by side. Both operands need the same number of rows. The result has this.columns + other.columns columns.
• other passes through Matrix.checkMatrix, meaning a plain 2D array is accepted.
• Neither operand is mutated. The result is a plain Matrix, including when the receiver is a view, a SymmetricMatrix, a DistanceMatrix.
• A dimension mismatch throws a RangeError naming the dimension that has to match. An unknown dimension throws invalid option: <value>, matching sum, product, mean.

Values are copied once into a preallocated result through setSubMatrix, leaving a single allocation per call. Matrices with a zero dimension are handled, which keeps the result predictable when one side carries no data.

Example

const M = new Matrix([
  [1, 2],
  [3, 4],
]);

M.concat([[5, 6]]); // Matrix [[1, 2], [3, 4], [5, 6]]
M.concat(Matrix.columnVector([5, 6]), 'column'); // Matrix [[1, 2, 5], [3, 4, 6]]

Chaining covers more than two operands, as in a.concat(b).concat(c).

The typing in matrix.d.ts is updated alongside the implementation. The README gains a short example under the existing examples section.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.73%. Comparing base (ee13f4b) to head (e420665).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #215      +/-   ##
==========================================
+ Coverage   68.58%   68.73%   +0.15%     
==========================================
  Files          49       49              
  Lines        5847     5876      +29     
  Branches     1042     1050       +8     
==========================================
+ Hits         4010     4039      +29     
  Misses       1824     1824              
  Partials       13       13              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.