nalgebra icon indicating copy to clipboard operation
nalgebra copied to clipboard

Consider renaming matrix slice to "matrix view"

Open Andlon opened this issue 3 years ago • 1 comments

Motivation

A "matrix slice" is indeed analogous to Rust slices (&[T]), so the name isn't inherently problematic. However, the terminology quickly becomes ambiguous. For example, consider the following methods from nalgebra's API:

There are many more examples in the API, I'm just trying to point out how our current terminology leads to ambiguous naming. I therefore suggest that we rename our current slice types to view, e.g.:

MatrixSlice(Mut) -> MatrixView(Mut)

Similarly, the methods that actually return a MatrixSlice(Mut) would be renamed from *slice* to *view*.

I am however not only motivated by fixing up inconsistencies: I'm sorely in need of a method that, given any matrix, gives me a matrix slice. The reason is that I have many APIs that take e.g. a DMatrixSlice(Mut):

fn compute_something<T>(input: DMatrixSlice<T>, output: DMatrixSliceMut<T>);

and calling these methods is often a bit of a pain, e.g.

compute_something(DMatrixSlice::from(&input), DMatrixSliceMut::from(&output));

With the new terminology we could provide a method named as_view(_mut) that would simply return the same matrix as a view:

compute_something(input.as_view(), output.as_view_mut());

Implementation

In order to avoid breaking everybody's code, it looks to me as if it would be plausible to do the rename in a fairly smooth way:

  • Rename current slice types to *View(Mut).
  • Provide type aliases for the existing Slice names, e.g. MatrixSlice = MatrixView.
  • Duplicate existing _slice_ methods that work with matrix slices as _view_
  • Mark the existing _slice_ methods as deprecated.
  • Update documentation and user guide (a bit of work probably).

I think this way we don't get direct breakage but users will just receive deprecation warnings. I also believe for most users the upgrade is a simply manner of Search + Replace (e.g. MatrixSlice -> MatrixView). Then in a few releases' time we can remove the deprecated methods.

I'd be happy to make the changes necessary, but I'd like to get some feedback first: are there compelling reasons against this change? Should we bikeshed over naming? (though I struggle to imagine there's a better name than View, but I may be surprised!) Open to feedback!

Since this is a somewhat sweeping change, it would be great to have your thoughts on this @sebcrozet. (I think we've briefly discussed it on Discord in the past)

Andlon avatar Feb 11 '22 12:02 Andlon

This sounds perfect to me. The motivation makes complete sense. And I think that view is a good choice. Other crates like ndarray use that terminology too.

sebcrozet avatar Feb 11 '22 12:02 sebcrozet