Skip to content

Add fallible runtime matrix dispatch and contextual index errors #109

@acgetchell

Description

@acgetchell

Summary

Downstream crates that need to bridge runtime matrix dimensions into Matrix<const D: usize> currently have to hand-roll local dispatch macros. In delaunay, predicate matrices use runtime sizes such as D + 1 and D + 2, then dispatch to stack matrices for dimensions up to the supported limit. The local workaround is a match k { 0..=7 => Matrix::<N>::zero(), _ => Err(...) } macro.

It would be useful for la-stack to expose a first-class fallible runtime-dimension dispatch helper so downstream crates do not need to duplicate this boilerplate or accidentally put a panic! behind public APIs.

Current State

  • Matrix<D> is const-generic and stack allocated, which is the right core model.
  • Matrix::get(r, c) returns Option<f64>.
  • Matrix::set(r, c, value) returns bool.
  • Consumers with caller-controlled runtime dimensions must implement their own dispatch layer.
  • When get / set fail, the returned Option / bool loses row, column, and matrix-dimension context unless the downstream crate rebuilds that context itself.

Proposed Changes

  1. Add a public fallible runtime dispatch helper or macro, for example:

    try_with_stack_matrix!(k, |m| -> Result<T, E> {
        // m has concrete type Matrix<N> for the selected N
    })

    Naming is flexible. The important contract is that unsupported dimensions return a typed error rather than panic.

  2. Add a typed unsupported-dimension error, either as a new LaError variant or as a small dedicated dispatch error:

    UnsupportedDimension { requested: usize, max: usize }
  3. Consider adding contextual checked index methods alongside the existing low-friction APIs:

    Matrix::get_checked(row, col) -> Result<f64, LaError>
    Matrix::set_checked(row, col, value) -> Result<(), LaError>

    This likely wants a typed error such as:

    IndexOutOfBounds { row: usize, col: usize, dim: usize }

    The existing get -> Option and set -> bool APIs can remain for const/hot paths that intentionally do not need error context.

Benefits

  • Keeps panic-free public API boundaries easier for downstream crates.
  • Avoids repeated local match macros across geometry crates.
  • Preserves la-stack's const-generic, stack-allocated core while improving ergonomics at runtime/const-generic boundaries.
  • Makes structural matrix mistakes debuggable without downstream crates inventing parallel error enums.

Implementation Notes

This came up while hardening delaunay predicate matrix code. delaunay had a local with_la_stack_matrix! macro whose unsupported-dimension branch could panic if reached from a public path. The crate now uses a local fallible dispatch macro and maps structural matrix mismatches into typed predicate errors, but that code is generic enough that it would be better owned by la-stack.

Target suggestion: v0.4.2 if this fits the patch/minor planning.

Metadata

Metadata

Assignees

No one assigned

    Labels

    apienhancementNew feature or requestrustPull requests that update rust code

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions