# Sparse Index Type (u32)
## Summary
Every sparse matrix storage format — COO, CSR, and CSC — represents row indices, column
indices, and row/column pointer arrays as `u32`, not `usize`. Any value that would not
fit in a `u32` is rejected through the format's own error type at the point it would be
stored, rather than being truncated or silently wrapped.
## Scope
Applies to the internal index storage of `CooMatrix`, `CsrMatrix`, and `CscMatrix`
(`row_indices`/`col_indices`, `row_ptr`/`col_ptr`), and to every operation that produces
or consumes those arrays: format construction, COO/CSR/CSC conversion, `spmm`, `matmat`,
`add`, entry pruning, and validation. It does not apply to matrix dimensions themselves
(`rows`, `cols`), which remain `usize`, or to scalar values stored in the matrix.
## Decision
Index and pointer arrays are `Vec<u32>` (owned) and `&[u32]` (borrowed) throughout the
sparse module. Any point where a `usize` value — a dimension, a running count, a computed
offset — must be written into one of these arrays goes through a checked conversion
(`u32::try_from`) or checked arithmetic (`checked_add`, `checked_mul`), and a failure
there is surfaced as the format's `DimensionOverflow` error variant. Constructors and
conversions never truncate a `usize` into a `u32` with an `as` cast where the value could
plausibly exceed `u32::MAX`.
## Constraints
- Index arrays, not values, dominate memory use for sparse formats at typical sparsity
levels — a CSR matrix with more rows/columns than nonzeros spends more memory on
`row_ptr` and `col_indices` than on the stored values themselves. Halving the width of
every index entry (`u32` versus a 64-bit `usize` on the platforms this library
primarily targets) is a direct, unconditional reduction in that footprint, which
matters most on RAM-constrained targets.
- No operation may panic or silently wrap on a value that doesn't fit — every narrowing
conversion from `usize` to `u32` must be checked and reported through the crate's
existing `Result`-based error model.
- `u32::MAX` (4,294,967,295) rows or columns is far beyond what a sparse matrix on a
memory-constrained target could hold in the first place, so the narrower range is not
a realistic ceiling in practice, while the memory savings apply to every matrix
regardless of size.
## Status
Implemented. All format constructors, conversions, and sparse operations (`spmm`,
`matmat`, `add`, prune, validate) that write into an index or pointer array go through a
checked path and return `DimensionOverflow` on failure instead of wrapping.