From 0319d236af74b3960b493829ca245d37a8de7629 Mon Sep 17 00:00:00 2001 From: Andreas Longva Date: Mon, 14 Nov 2022 14:02:36 +0100 Subject: [PATCH] Deprecate+rename methods for slicing --- src/base/construction_view.rs | 36 ++--- src/base/indexing.rs | 2 +- src/base/matrix.rs | 14 +- src/base/matrix_view.rs | 277 +++++++++++++++++++++++----------- 4 files changed, 213 insertions(+), 116 deletions(-) diff --git a/src/base/construction_view.rs b/src/base/construction_view.rs index aa355264..fbb038cb 100644 --- a/src/base/construction_view.rs +++ b/src/base/construction_view.rs @@ -4,11 +4,11 @@ use crate::base::{MatrixView, MatrixViewMut, Scalar}; use num_rational::Ratio; -/// # Creating matrix slices from `&[T]` +/// # Creating matrix views from `&[T]` impl<'a, T: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> MatrixView<'a, T, R, C, RStride, CStride> { - /// Creates, without bound-checking, a matrix slice from an array and with dimensions and strides specified by generic types instances. + /// Creates, without bounds checking, a matrix view from an array and with dimensions and strides specified by generic types instances. /// /// # Safety /// This method is unsafe because the input data array is not checked to contain enough elements. @@ -30,7 +30,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> Self::from_data(data) } - /// Creates a matrix slice from an array and with dimensions and strides specified by generic types instances. + /// Creates a matrix view from an array and with dimensions and strides specified by generic types instances. /// /// Panics if the input data array dose not contain enough elements. /// The generic types `R`, `C`, `RStride`, `CStride` can either be type-level integers or integers wrapped with `Dynamic::new()`. @@ -58,7 +58,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> } impl<'a, T: Scalar, R: Dim, C: Dim> MatrixView<'a, T, R, C> { - /// Creates, without bound-checking, a matrix slice from an array and with dimensions specified by generic types instances. + /// Creates, without bound-checking, a matrix view from an array and with dimensions specified by generic types instances. /// /// # Safety /// This method is unsafe because the input data array is not checked to contain enough elements. @@ -75,7 +75,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim> MatrixView<'a, T, R, C> { ) } - /// Creates a matrix slice from an array and with dimensions and strides specified by generic types instances. + /// Creates a matrix view from an array and with dimensions and strides specified by generic types instances. /// /// Panics if the input data array dose not contain enough elements. /// The generic types `R` and `C` can either be type-level integers or integers wrapped with `Dynamic::new()`. @@ -88,7 +88,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim> MatrixView<'a, T, R, C> { macro_rules! impl_constructors( ($($Dims: ty),*; $(=> $DimIdent: ident: $DimBound: ident),*; $($gargs: expr),*; $($args: ident),*) => { impl<'a, T: Scalar, $($DimIdent: $DimBound),*> MatrixView<'a, T, $($Dims),*> { - /// Creates a new matrix slice from the given data array. + /// Creates a new matrix view from the given data array. /// /// Panics if `data` does not contain enough elements. #[inline] @@ -96,7 +96,7 @@ macro_rules! impl_constructors( Self::from_slice_generic(data, $($gargs),*) } - /// Creates, without bound checking, a new matrix slice from the given data array. + /// Creates, without bound checking, a new matrix view from the given data array. #[inline] pub unsafe fn from_slice_unchecked(data: &'a [T], start: usize, $($args: usize),*) -> Self { Self::from_slice_generic_unchecked(data, start, $($gargs),*) @@ -104,7 +104,7 @@ macro_rules! impl_constructors( } impl<'a, T: Scalar, $($DimIdent: $DimBound, )*> MatrixView<'a, T, $($Dims,)* Dynamic, Dynamic> { - /// Creates a new matrix slice with the specified strides from the given data array. + /// Creates a new matrix view with the specified strides from the given data array. /// /// Panics if `data` does not contain enough elements. #[inline] @@ -112,7 +112,7 @@ macro_rules! impl_constructors( Self::from_slice_with_strides_generic(data, $($gargs,)* Dynamic::new(rstride), Dynamic::new(cstride)) } - /// Creates, without bound checking, a new matrix slice with the specified strides from the given data array. + /// Creates, without bound checking, a new matrix view with the specified strides from the given data array. #[inline] pub unsafe fn from_slice_with_strides_unchecked(data: &'a [T], start: usize, $($args: usize,)* rstride: usize, cstride: usize) -> Self { Self::from_slice_with_strides_generic_unchecked(data, start, $($gargs,)* Dynamic::new(rstride), Dynamic::new(cstride)) @@ -142,11 +142,11 @@ impl_constructors!(Dynamic, Dynamic; Dynamic::new(nrows), Dynamic::new(ncols); nrows, ncols); -/// # Creating mutable matrix slices from `&mut [T]` +/// # Creating mutable matrix views from `&mut [T]` impl<'a, T: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> MatrixViewMut<'a, T, R, C, RStride, CStride> { - /// Creates, without bound-checking, a mutable matrix slice from an array and with dimensions and strides specified by generic types instances. + /// Creates, without bound-checking, a mutable matrix view from an array and with dimensions and strides specified by generic types instances. /// /// # Safety /// This method is unsafe because the input data array is not checked to contain enough elements. @@ -168,7 +168,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> Self::from_data(data) } - /// Creates a mutable matrix slice from an array and with dimensions and strides specified by generic types instances. + /// Creates a mutable matrix view from an array and with dimensions and strides specified by generic types instances. /// /// Panics if the input data array dose not contain enough elements. /// The generic types `R`, `C`, `RStride`, `CStride` can either be type-level integers or integers wrapped with `Dynamic::new()`. @@ -218,7 +218,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim, RStride: Dim, CStride: Dim> } impl<'a, T: Scalar, R: Dim, C: Dim> MatrixViewMut<'a, T, R, C> { - /// Creates, without bound-checking, a mutable matrix slice from an array and with dimensions specified by generic types instances. + /// Creates, without bound-checking, a mutable matrix view from an array and with dimensions specified by generic types instances. /// /// # Safety /// This method is unsafe because the input data array is not checked to contain enough elements. @@ -235,7 +235,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim> MatrixViewMut<'a, T, R, C> { ) } - /// Creates a mutable matrix slice from an array and with dimensions and strides specified by generic types instances. + /// Creates a mutable matrix view from an array and with dimensions and strides specified by generic types instances. /// /// Panics if the input data array dose not contain enough elements. /// The generic types `R` and `C` can either be type-level integers or integers wrapped with `Dynamic::new()`. @@ -248,7 +248,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim> MatrixViewMut<'a, T, R, C> { macro_rules! impl_constructors_mut( ($($Dims: ty),*; $(=> $DimIdent: ident: $DimBound: ident),*; $($gargs: expr),*; $($args: ident),*) => { impl<'a, T: Scalar, $($DimIdent: $DimBound),*> MatrixViewMut<'a, T, $($Dims),*> { - /// Creates a new mutable matrix slice from the given data array. + /// Creates a new mutable matrix view from the given data array. /// /// Panics if `data` does not contain enough elements. #[inline] @@ -256,7 +256,7 @@ macro_rules! impl_constructors_mut( Self::from_slice_generic(data, $($gargs),*) } - /// Creates, without bound checking, a new mutable matrix slice from the given data array. + /// Creates, without bound checking, a new mutable matrix view from the given data array. #[inline] pub unsafe fn from_slice_unchecked(data: &'a mut [T], start: usize, $($args: usize),*) -> Self { Self::from_slice_generic_unchecked(data, start, $($gargs),*) @@ -264,7 +264,7 @@ macro_rules! impl_constructors_mut( } impl<'a, T: Scalar, $($DimIdent: $DimBound, )*> MatrixViewMut<'a, T, $($Dims,)* Dynamic, Dynamic> { - /// Creates a new mutable matrix slice with the specified strides from the given data array. + /// Creates a new mutable matrix view with the specified strides from the given data array. /// /// Panics if `data` does not contain enough elements. #[inline] @@ -273,7 +273,7 @@ macro_rules! impl_constructors_mut( data, $($gargs,)* Dynamic::new(rstride), Dynamic::new(cstride)) } - /// Creates, without bound checking, a new mutable matrix slice with the specified strides from the given data array. + /// Creates, without bound checking, a new mutable matrix view with the specified strides from the given data array. #[inline] pub unsafe fn from_slice_with_strides_unchecked(data: &'a mut [T], start: usize, $($args: usize,)* rstride: usize, cstride: usize) -> Self { Self::from_slice_with_strides_generic_unchecked( diff --git a/src/base/indexing.rs b/src/base/indexing.rs index df769163..ceefe91e 100644 --- a/src/base/indexing.rs +++ b/src/base/indexing.rs @@ -378,7 +378,7 @@ pub trait MatrixIndexMut<'a, T, R: Dim, C: Dim, S: RawStorageMut>: } } -/// # Slicing based on ranges +/// # Views based on ranges /// ## Indices to Individual Elements /// ### Two-Dimensional Indices /// ``` diff --git a/src/base/matrix.rs b/src/base/matrix.rs index 659d3a6e..ae2f51e9 100644 --- a/src/base/matrix.rs +++ b/src/base/matrix.rs @@ -99,13 +99,13 @@ pub type MatrixCross = /// - [Elementwise mapping and folding `map`, `fold`, `zip_map`…](#elementwise-mapping-and-folding) /// - [Folding or columns and rows `compress_rows`, `compress_columns`…](#folding-on-columns-and-rows) /// -/// #### Vector and matrix slicing -/// - [Creating matrix slices from `&[T]` `from_slice`, `from_slice_with_strides`…](#creating-matrix-slices-from-t) -/// - [Creating mutable matrix slices from `&mut [T]` `from_slice_mut`, `from_slice_with_strides_mut`…](#creating-mutable-matrix-slices-from-mut-t) -/// - [Slicing based on index and length `row`, `columns`, `slice`…](#slicing-based-on-index-and-length) -/// - [Mutable slicing based on index and length `row_mut`, `columns_mut`, `slice_mut`…](#mutable-slicing-based-on-index-and-length) -/// - [Slicing based on ranges `rows_range`, `columns_range`…](#slicing-based-on-ranges) -/// - [Mutable slicing based on ranges `rows_range_mut`, `columns_range_mut`…](#mutable-slicing-based-on-ranges) +/// #### Vector and matrix views +/// - [Creating matrix views from `&[T]` `from_slice`, `from_slice_with_strides`…](#creating-matrix-views-from-t) +/// - [Creating mutable matrix views from `&mut [T]` `from_slice_mut`, `from_slice_with_strides_mut`…](#creating-mutable-matrix-views-from-mut-t) +/// - [Views based on index and length `row`, `columns`, `view`…](#views-based-on-index-and-length) +/// - [Mutable views based on index and length `row_mut`, `columns_mut`, `view_mut`…](#mutable-views-based-on-index-and-length) +/// - [Views based on ranges `rows_range`, `columns_range`…](#views-based-on-ranges) +/// - [Mutable views based on ranges `rows_range_mut`, `columns_range_mut`…](#mutable-views-based-on-ranges) /// /// #### In-place modification of a single matrix or vector /// - [In-place filling `fill`, `fill_diagonal`, `fill_with_identity`…](#in-place-filling) diff --git a/src/base/matrix_view.rs b/src/base/matrix_view.rs index 03d06778..d37346a6 100644 --- a/src/base/matrix_view.rs +++ b/src/base/matrix_view.rs @@ -284,7 +284,7 @@ impl> Matrix { } } -macro_rules! matrix_slice_impl ( +macro_rules! matrix_view_impl ( ($me: ident: $Me: ty, $MatrixView: ident, $ViewStorage: ident, $Storage: ident.$get_addr: ident (), $data: expr; $row: ident, $row_part: ident, @@ -302,12 +302,12 @@ macro_rules! matrix_slice_impl ( $fixed_columns_with_step: ident, $columns_generic: ident, $columns_generic_with_step: ident, - $slice: ident, - $slice_with_steps: ident, - $fixed_slice: ident, - $fixed_slice_with_steps: ident, - $generic_slice: ident, - $generic_slice_with_steps: ident, + $slice: ident => $view:ident, + $slice_with_steps: ident => $view_with_steps:ident, + $fixed_slice: ident => $fixed_view:ident, + $fixed_slice_with_steps: ident => $fixed_view_with_steps:ident, + $generic_slice: ident => $generic_view:ident, + $generic_slice_with_steps: ident => $generic_view_with_steps:ident, $rows_range_pair: ident, $columns_range_pair: ident) => { /* @@ -315,13 +315,13 @@ macro_rules! matrix_slice_impl ( * Row slicing. * */ - /// Returns a slice containing the i-th row of this matrix. + /// Returns a view containing the i-th row of this matrix. #[inline] pub fn $row($me: $Me, i: usize) -> $MatrixView<'_, T, U1, C, S::RStride, S::CStride> { $me.$fixed_rows::<1>(i) } - /// Returns a slice containing the `n` first elements of the i-th row of this matrix. + /// Returns a view containing the `n` first elements of the i-th row of this matrix. #[inline] pub fn $row_part($me: $Me, i: usize, n: usize) -> $MatrixView<'_, T, U1, Dynamic, S::RStride, S::CStride> { $me.$generic_slice((i, 0), (Const::<1>, Dynamic::new(n))) @@ -345,26 +345,26 @@ macro_rules! matrix_slice_impl ( /// Extracts a compile-time number of consecutive rows from this matrix. #[inline] - pub fn $fixed_rows($me: $Me, first_row: usize) - -> $MatrixView<'_, T, Const, C, S::RStride, S::CStride> { + pub fn $fixed_rows($me: $Me, first_row: usize) + -> $MatrixView<'_, T, Const, C, S::RStride, S::CStride> { - $me.$rows_generic(first_row, Const::) + $me.$rows_generic(first_row, Const::) } /// Extracts from this matrix a compile-time number of rows regularly skipping `step` /// rows. #[inline] - pub fn $fixed_rows_with_step($me: $Me, first_row: usize, step: usize) - -> $MatrixView<'_, T, Const, C, Dynamic, S::CStride> { + pub fn $fixed_rows_with_step($me: $Me, first_row: usize, step: usize) + -> $MatrixView<'_, T, Const, C, Dynamic, S::CStride> { - $me.$rows_generic_with_step(first_row, Const::, step) + $me.$rows_generic_with_step(first_row, Const::, step) } /// Extracts from this matrix `nrows` rows regularly skipping `step` rows. Both /// argument may or may not be values known at compile-time. #[inline] - pub fn $rows_generic($me: $Me, row_start: usize, nrows: RSlice) - -> $MatrixView<'_, T, RSlice, C, S::RStride, S::CStride> { + pub fn $rows_generic($me: $Me, row_start: usize, nrows: RView) + -> $MatrixView<'_, T, RView, C, S::RStride, S::CStride> { let my_shape = $me.shape_generic(); $me.assert_slice_index((row_start, 0), (nrows.value(), my_shape.1.value()), (0, 0)); @@ -380,9 +380,9 @@ macro_rules! matrix_slice_impl ( /// Extracts from this matrix `nrows` rows regularly skipping `step` rows. Both /// argument may or may not be values known at compile-time. #[inline] - pub fn $rows_generic_with_step($me: $Me, row_start: usize, nrows: RSlice, step: usize) - -> $MatrixView<'_, T, RSlice, C, Dynamic, S::CStride> - where RSlice: Dim { + pub fn $rows_generic_with_step($me: $Me, row_start: usize, nrows: RView, step: usize) + -> $MatrixView<'_, T, RView, C, Dynamic, S::CStride> + where RView: Dim { let my_shape = $me.shape_generic(); let my_strides = $me.data.strides(); @@ -402,16 +402,16 @@ macro_rules! matrix_slice_impl ( * Column slicing. * */ - /// Returns a slice containing the i-th column of this matrix. + /// Returns a view containing the i-th column of this matrix. #[inline] pub fn $column($me: $Me, i: usize) -> $MatrixView<'_, T, R, U1, S::RStride, S::CStride> { $me.$fixed_columns::<1>(i) } - /// Returns a slice containing the `n` first elements of the i-th column of this matrix. + /// Returns a view containing the `n` first elements of the i-th column of this matrix. #[inline] pub fn $column_part($me: $Me, i: usize, n: usize) -> $MatrixView<'_, T, Dynamic, U1, S::RStride, S::CStride> { - $me.$generic_slice((0, i), (Dynamic::new(n), Const::<1>)) + $me.$generic_view((0, i), (Dynamic::new(n), Const::<1>)) } /// Extracts from this matrix a set of consecutive columns. @@ -433,26 +433,26 @@ macro_rules! matrix_slice_impl ( /// Extracts a compile-time number of consecutive columns from this matrix. #[inline] - pub fn $fixed_columns($me: $Me, first_col: usize) - -> $MatrixView<'_, T, R, Const, S::RStride, S::CStride> { + pub fn $fixed_columns($me: $Me, first_col: usize) + -> $MatrixView<'_, T, R, Const, S::RStride, S::CStride> { - $me.$columns_generic(first_col, Const::) + $me.$columns_generic(first_col, Const::) } /// Extracts from this matrix a compile-time number of columns regularly skipping /// `step` columns. #[inline] - pub fn $fixed_columns_with_step($me: $Me, first_col: usize, step: usize) - -> $MatrixView<'_, T, R, Const, S::RStride, Dynamic> { + pub fn $fixed_columns_with_step($me: $Me, first_col: usize, step: usize) + -> $MatrixView<'_, T, R, Const, S::RStride, Dynamic> { - $me.$columns_generic_with_step(first_col, Const::, step) + $me.$columns_generic_with_step(first_col, Const::, step) } /// Extracts from this matrix `ncols` columns. The number of columns may or may not be /// known at compile-time. #[inline] - pub fn $columns_generic($me: $Me, first_col: usize, ncols: CSlice) - -> $MatrixView<'_, T, R, CSlice, S::RStride, S::CStride> { + pub fn $columns_generic($me: $Me, first_col: usize, ncols: CView) + -> $MatrixView<'_, T, R, CView, S::RStride, S::CStride> { let my_shape = $me.shape_generic(); $me.assert_slice_index((0, first_col), (my_shape.0.value(), ncols.value()), (0, 0)); @@ -468,8 +468,8 @@ macro_rules! matrix_slice_impl ( /// Extracts from this matrix `ncols` columns skipping `step` columns. Both argument may /// or may not be values known at compile-time. #[inline] - pub fn $columns_generic_with_step($me: $Me, first_col: usize, ncols: CSlice, step: usize) - -> $MatrixView<'_, T, R, CSlice, S::RStride, Dynamic> { + pub fn $columns_generic_with_step($me: $Me, first_col: usize, ncols: CView, step: usize) + -> $MatrixView<'_, T, R, CView, S::RStride, Dynamic> { let my_shape = $me.shape_generic(); let my_strides = $me.data.strides(); @@ -493,8 +493,17 @@ macro_rules! matrix_slice_impl ( /// Slices this matrix starting at its component `(irow, icol)` and with `(nrows, ncols)` /// consecutive elements. #[inline] + #[deprecated = slice_deprecation_note!($view)] pub fn $slice($me: $Me, start: (usize, usize), shape: (usize, usize)) -> $MatrixView<'_, T, Dynamic, Dynamic, S::RStride, S::CStride> { + $me.$view(start, shape) + } + + /// Return a view of this matrix starting at its component `(irow, icol)` and with `(nrows, ncols)` + /// consecutive elements. + #[inline] + pub fn $view($me: $Me, start: (usize, usize), shape: (usize, usize)) + -> $MatrixView<'_, T, Dynamic, Dynamic, S::RStride, S::CStride> { $me.assert_slice_index(start, shape, (0, 0)); let shape = (Dynamic::new(shape.0), Dynamic::new(shape.1)); @@ -505,27 +514,45 @@ macro_rules! matrix_slice_impl ( } } - /// Slices this matrix starting at its component `(start.0, start.1)` and with /// `(shape.0, shape.1)` components. Each row (resp. column) of the sliced matrix is /// separated by `steps.0` (resp. `steps.1`) ignored rows (resp. columns) of the /// original matrix. #[inline] + #[deprecated = slice_deprecation_note!($view_with_steps)] pub fn $slice_with_steps($me: $Me, start: (usize, usize), shape: (usize, usize), steps: (usize, usize)) -> $MatrixView<'_, T, Dynamic, Dynamic, Dynamic, Dynamic> { - let shape = (Dynamic::new(shape.0), Dynamic::new(shape.1)); + $me.$view_with_steps(start, shape, steps) + } - $me.$generic_slice_with_steps(start, shape, steps) + /// Return a view of this matrix starting at its component `(start.0, start.1)` and with + /// `(shape.0, shape.1)` components. Each row (resp. column) of the matrix view is + /// separated by `steps.0` (resp. `steps.1`) ignored rows (resp. columns) of the + /// original matrix. + #[inline] + pub fn $view_with_steps($me: $Me, start: (usize, usize), shape: (usize, usize), steps: (usize, usize)) + -> $MatrixView<'_, T, Dynamic, Dynamic, Dynamic, Dynamic> { + let shape = (Dynamic::new(shape.0), Dynamic::new(shape.1)); + $me.$generic_view_with_steps(start, shape, steps) } /// Slices this matrix starting at its component `(irow, icol)` and with `(R::dim(), - /// CSlice::dim())` consecutive components. + /// CView::dim())` consecutive components. #[inline] - pub fn $fixed_slice($me: $Me, irow: usize, icol: usize) - -> $MatrixView<'_, T, Const, Const, S::RStride, S::CStride> { + #[deprecated = slice_deprecation_note!($fixed_view)] + pub fn $fixed_slice($me: $Me, irow: usize, icol: usize) + -> $MatrixView<'_, T, Const, Const, S::RStride, S::CStride> { + $me.$fixed_view(irow, icol) + } - $me.assert_slice_index((irow, icol), (RSLICE, CSLICE), (0, 0)); - let shape = (Const::, Const::); + /// Return a view of this matrix starting at its component `(irow, icol)` and with `(R::dim(), + /// CView::dim())` consecutive components. + #[inline] + pub fn $fixed_view($me: $Me, irow: usize, icol: usize) + -> $MatrixView<'_, T, Const, Const, S::RStride, S::CStride> { + + $me.assert_slice_index((irow, icol), (RVIEW, CVIEW), (0, 0)); + let shape = (Const::, Const::); unsafe { let data = $ViewStorage::new_unchecked($data, (irow, icol), shape); @@ -534,22 +561,43 @@ macro_rules! matrix_slice_impl ( } /// Slices this matrix starting at its component `(start.0, start.1)` and with - /// `(RSLICE, CSLICE)` components. Each row (resp. column) of the sliced + /// `(RVIEW, CVIEW)` components. Each row (resp. column) of the sliced /// matrix is separated by `steps.0` (resp. `steps.1`) ignored rows (resp. columns) of /// the original matrix. #[inline] - pub fn $fixed_slice_with_steps($me: $Me, start: (usize, usize), steps: (usize, usize)) - -> $MatrixView<'_, T, Const, Const, Dynamic, Dynamic> { - let shape = (Const::, Const::); - $me.$generic_slice_with_steps(start, shape, steps) + #[deprecated = slice_deprecation_note!($fixed_view_with_steps)] + pub fn $fixed_slice_with_steps($me: $Me, start: (usize, usize), steps: (usize, usize)) + -> $MatrixView<'_, T, Const, Const, Dynamic, Dynamic> { + $me.$fixed_view_with_steps(start, steps) + } + + /// Returns a view of this matrix starting at its component `(start.0, start.1)` and with + /// `(RVIEW, CVIEW)` components. Each row (resp. column) of the matrix view + /// is separated by `steps.0` (resp. `steps.1`) ignored rows (resp. columns) of + /// the original matrix. + #[inline] + pub fn $fixed_view_with_steps($me: $Me, start: (usize, usize), steps: (usize, usize)) + -> $MatrixView<'_, T, Const, Const, Dynamic, Dynamic> { + let shape = (Const::, Const::); + $me.$generic_view_with_steps(start, shape, steps) } /// Creates a slice that may or may not have a fixed size and stride. #[inline] - pub fn $generic_slice($me: $Me, start: (usize, usize), shape: (RSlice, CSlice)) - -> $MatrixView<'_, T, RSlice, CSlice, S::RStride, S::CStride> - where RSlice: Dim, - CSlice: Dim { + #[deprecated = slice_deprecation_note!($generic_view)] + pub fn $generic_slice($me: $Me, start: (usize, usize), shape: (RView, CView)) + -> $MatrixView<'_, T, RView, CView, S::RStride, S::CStride> + where RView: Dim, + CView: Dim { + $me.$generic_view(start, shape) + } + + /// Creates a matrix view that may or may not have a fixed size and stride. + #[inline] + pub fn $generic_view($me: $Me, start: (usize, usize), shape: (RView, CView)) + -> $MatrixView<'_, T, RView, CView, S::RStride, S::CStride> + where RView: Dim, + CView: Dim { $me.assert_slice_index(start, (shape.0.value(), shape.1.value()), (0, 0)); @@ -561,13 +609,26 @@ macro_rules! matrix_slice_impl ( /// Creates a slice that may or may not have a fixed size and stride. #[inline] - pub fn $generic_slice_with_steps($me: $Me, + #[deprecated = slice_deprecation_note!($generic_view_with_steps)] + pub fn $generic_slice_with_steps($me: $Me, start: (usize, usize), - shape: (RSlice, CSlice), + shape: (RView, CView), steps: (usize, usize)) - -> $MatrixView<'_, T, RSlice, CSlice, Dynamic, Dynamic> - where RSlice: Dim, - CSlice: Dim { + -> $MatrixView<'_, T, RView, CView, Dynamic, Dynamic> + where RView: Dim, + CView: Dim { + $me.$generic_view_with_steps(start, shape, steps) + } + + /// Creates a matrix view that may or may not have a fixed size and stride. + #[inline] + pub fn $generic_view_with_steps($me: $Me, + start: (usize, usize), + shape: (RView, CView), + steps: (usize, usize)) + -> $MatrixView<'_, T, RView, CView, Dynamic, Dynamic> + where RView: Dim, + CView: Dim { $me.assert_slice_index(start, (shape.0.value(), shape.1.value()), steps); @@ -615,10 +676,10 @@ macro_rules! matrix_slice_impl ( let data1 = $ViewStorage::from_raw_parts(ptr1, (nrows1, ncols), strides); let data2 = $ViewStorage::from_raw_parts(ptr2, (nrows2, ncols), strides); - let slice1 = Matrix::from_data_statically_unchecked(data1); - let slice2 = Matrix::from_data_statically_unchecked(data2); + let view1 = Matrix::from_data_statically_unchecked(data1); + let view2 = Matrix::from_data_statically_unchecked(data2); - (slice1, slice2) + (view1, view2) } } @@ -651,10 +712,10 @@ macro_rules! matrix_slice_impl ( let data1 = $ViewStorage::from_raw_parts(ptr1, (nrows, ncols1), strides); let data2 = $ViewStorage::from_raw_parts(ptr2, (nrows, ncols2), strides); - let slice1 = Matrix::from_data_statically_unchecked(data1); - let slice2 = Matrix::from_data_statically_unchecked(data2); + let view1 = Matrix::from_data_statically_unchecked(data1); + let view2 = Matrix::from_data_statically_unchecked(data2); - (slice1, slice2) + (view1, view2) } } } @@ -688,9 +749,9 @@ pub type MatrixSliceMut<'a, T, R, C, RStride = U1, CStride = R> = pub type MatrixViewMut<'a, T, R, C, RStride = U1, CStride = R> = Matrix>; -/// # Slicing based on index and length +/// # Views based on index and length impl> Matrix { - matrix_slice_impl!( + matrix_view_impl!( self: &Self, MatrixView, ViewStorage, RawStorage.get_address_unchecked(), &self.data; row, row_part, @@ -708,19 +769,19 @@ impl> Matrix { fixed_columns_with_step, columns_generic, columns_generic_with_step, - slice, - slice_with_steps, - fixed_slice, - fixed_slice_with_steps, - generic_slice, - generic_slice_with_steps, + slice => view, + slice_with_steps => view_with_steps, + fixed_slice => fixed_view, + fixed_slice_with_steps => fixed_view_with_steps, + generic_slice => generic_view, + generic_slice_with_steps => generic_view_with_steps, rows_range_pair, columns_range_pair); } -/// # Mutable slicing based on index and length +/// # Mutable views based on index and length impl> Matrix { - matrix_slice_impl!( + matrix_view_impl!( self: &mut Self, MatrixViewMut, ViewStorageMut, RawStorageMut.get_address_unchecked_mut(), &mut self.data; row_mut, row_part_mut, @@ -738,12 +799,12 @@ impl> Matrix { fixed_columns_with_step_mut, columns_generic_mut, columns_generic_with_step_mut, - slice_mut, - slice_with_steps_mut, - fixed_slice_mut, - fixed_slice_with_steps_mut, - generic_slice_mut, - generic_slice_with_steps_mut, + slice_mut => view_mut, + slice_with_steps_mut => view_with_steps_mut, + fixed_slice_mut => fixed_view_mut, + fixed_slice_with_steps_mut => fixed_view_with_steps_mut, + generic_slice_mut => generic_view_mut, + generic_slice_with_steps_mut => generic_view_with_steps_mut, rows_range_pair_mut, columns_range_pair_mut); } @@ -889,6 +950,7 @@ impl> Matrix { /// by the range `cols`. #[inline] #[must_use] + #[deprecated = slice_deprecation_note!(view_range)] pub fn slice_range( &self, rows: RowRange, @@ -905,24 +967,44 @@ impl> Matrix { ) } - /// Slice containing all the rows indexed by the range `rows`. + /// Returns a view containing the rows indexed by the range `rows` and the columns indexed + /// by the range `cols`. + #[inline] + #[must_use] + pub fn view_range( + &self, + rows: RowRange, + cols: ColRange, + ) -> MatrixView<'_, T, RowRange::Size, ColRange::Size, S::RStride, S::CStride> + where + RowRange: SliceRange, + ColRange: SliceRange, + { + let (nrows, ncols) = self.shape_generic(); + self.generic_view( + (rows.begin(nrows), cols.begin(ncols)), + (rows.size(nrows), cols.size(ncols)), + ) + } + + /// View containing all the rows indexed by the range `rows`. #[inline] #[must_use] pub fn rows_range>( &self, rows: RowRange, ) -> MatrixView<'_, T, RowRange::Size, C, S::RStride, S::CStride> { - self.slice_range(rows, ..) + self.view_range(rows, ..) } - /// Slice containing all the columns indexed by the range `rows`. + /// View containing all the columns indexed by the range `rows`. #[inline] #[must_use] pub fn columns_range>( &self, cols: ColRange, ) -> MatrixView<'_, T, R, ColRange::Size, S::RStride, S::CStride> { - self.slice_range(.., cols) + self.view_range(.., cols) } } @@ -931,6 +1013,7 @@ impl> Matrix { impl> Matrix { /// Slices a mutable sub-matrix containing the rows indexed by the range `rows` and the columns /// indexed by the range `cols`. + #[deprecated = slice_deprecation_note!(view_range_mut)] pub fn slice_range_mut( &mut self, rows: RowRange, @@ -939,30 +1022,44 @@ impl> Matrix { where RowRange: SliceRange, ColRange: SliceRange, + { + self.view_range_mut(rows, cols) + } + + /// Return a mutable view containing the rows indexed by the range `rows` and the columns + /// indexed by the range `cols`. + pub fn view_range_mut( + &mut self, + rows: RowRange, + cols: ColRange, + ) -> MatrixViewMut<'_, T, RowRange::Size, ColRange::Size, S::RStride, S::CStride> + where + RowRange: SliceRange, + ColRange: SliceRange, { let (nrows, ncols) = self.shape_generic(); - self.generic_slice_mut( + self.generic_view_mut( (rows.begin(nrows), cols.begin(ncols)), (rows.size(nrows), cols.size(ncols)), ) } - /// Slice containing all the rows indexed by the range `rows`. + /// Mutable view containing all the rows indexed by the range `rows`. #[inline] pub fn rows_range_mut>( &mut self, rows: RowRange, ) -> MatrixViewMut<'_, T, RowRange::Size, C, S::RStride, S::CStride> { - self.slice_range_mut(rows, ..) + self.view_range_mut(rows, ..) } - /// Slice containing all the columns indexed by the range `cols`. + /// Mutable view containing all the columns indexed by the range `cols`. #[inline] pub fn columns_range_mut>( &mut self, cols: ColRange, ) -> MatrixViewMut<'_, T, R, ColRange::Size, S::RStride, S::CStride> { - self.slice_range_mut(.., cols) + self.view_range_mut(.., cols) } } @@ -974,11 +1071,11 @@ where RStride: Dim, CStride: Dim, { - fn from(slice_mut: MatrixViewMut<'a, T, R, C, RStride, CStride>) -> Self { + fn from(view_mut: MatrixViewMut<'a, T, R, C, RStride, CStride>) -> Self { let data = ViewStorage { - ptr: slice_mut.data.ptr, - shape: slice_mut.data.shape, - strides: slice_mut.data.strides, + ptr: view_mut.data.ptr, + shape: view_mut.data.shape, + strides: view_mut.data.strides, _phantoms: PhantomData, };