`@immut.Matrix`

This page documents the current 0.3.0 repository behavior.

Overview

@immut.Matrix uses value semantics.
Operations such as set, swap_rows, and swap_cols return a new matrix.
Matrix storage is row-major and backed by the immutable vector implementation.
Public indexed access is strict about bounds. m[row][col] and set(row, col, value) panic on out-of-range indices, including 0xN and Nx0 edge shapes.
swap_rows(i, i) and swap_cols(i, i) are no-op operations that return the original value unchanged.

Matrix::make(row, col, f) Creates a matrix from a generator function. Negative dimensions panic.
Matrix::new(row, col, elem) Creates a matrix filled with elem. Negative dimensions panic.
Matrix::from_2d_array(arr) Creates a matrix from a rectangular 2D array. Ragged input panics.
Matrix::from_array(row, col, data) Builds a matrix from a flat immutable vector in row-major order. Negative dimensions or wrong element count panic.
row() / col() Return the stored shape.
m[row][col] Read-only convenience indexing. Row and column bounds are checked explicitly.
set(row, col, elem) Returns a new matrix with one replaced element. Bounds are checked explicitly.
map, mapi Return transformed matrices without mutating the original.
transpose() Returns the materialized transpose.
horizontal_combine, vertical_combine Concatenate matrices with compatible shapes.
iter, iter_row, iter_col, to_array, to_2d_array Expose row-major iteration and materialized conversions. Row/column iterators panic on invalid indices.

+, -, * Addition, subtraction, and matrix multiplication. Shape mismatch panics.
scale(cst), add_constant(cst), unary - Element-wise scalar transforms.
identity(size) Creates an identity matrix. Negative size panics.
trace() Sum of diagonal entries. Requires a square matrix.
determinant() Determinant of a square matrix. Uses the current repository implementation with small-size specializations and elimination for larger inputs.
pow(power) Raises a square matrix to a non-negative integer power. Non-square matrices and negative exponents panic.
null(), is_square() Shape and zero-matrix helpers.
adjoint() Conjugate transpose for element types implementing Conjugate.
swap_rows(r1, r2), swap_cols(c1, c2) Return a new matrix with the chosen rows or columns swapped. Out-of-range indices panic; same-index swaps are no-op.

MatrixFn is the lazy functional companion to Matrix.
It follows the same non-negative-dimension rule.
MatrixFn::from_2d_array([]) yields a 0x0 matrix.
MatrixFn::from_2d_array([[], ...]) preserves zero-column shapes.
Ragged input is rejected eagerly.
Row access validates the row immediately, and element access validates the column through the functional backing contract.

Important methods:

For shared algebraic behavior, @immut.Matrix remains the semantic reference point used by the repository’s consistency tests.
The mutable package intentionally exposes extra execution-oriented APIs such as views and in-place updates; those should not be projected back onto immut.