From 2dc51e5b22c5dcd7b38203b3a0bb547d2bb3208c Mon Sep 17 00:00:00 2001 From: Jim Turner Date: Tue, 26 Feb 2019 20:20:22 -0500 Subject: [PATCH 1/2] Improve docs of .raw_dim(), .shape(), and .strides() --- src/impl_methods.rs | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/src/impl_methods.rs b/src/impl_methods.rs index de74af795..52b540f74 100644 --- a/src/impl_methods.rs +++ b/src/impl_methods.rs @@ -83,17 +83,43 @@ where } /// Return the shape of the array as it stored in the array. + /// + /// This is primarily useful for passing to other `ArrayBase` + /// functions, such as when creating another array of the same + /// shape and dimensionality. + /// + /// ``` + /// use ndarray::Array; + /// + /// let a = Array::from_elem((2, 3), 5.); + /// + /// // Create an array of zeros that's the same shape and dimensionality as `a`. + /// let b = Array::::zeros(a.raw_dim()); + /// ``` pub fn raw_dim(&self) -> D { self.dim.clone() } /// Return the shape of the array as a slice. - pub fn shape(&self) -> &[Ix] { + /// + /// Note that you probably don't want to use this to create an + /// array of the same shape as another array because creating an + /// array with e.g. [`Array::zeros()`](ArrayBase::zeros) using a + /// shape of type `&[usize]` results in a dynamic-dimensional + /// array. For example, if `arr` is of type `Array`, then + /// `Array::zeros(arr.shape())` returns an instance of type + /// `Array`, not `Array`. + /// + /// If you want to create an array that has the same shape and + /// dimensionality as another array, use + /// [`.raw_dim()`](ArrayBase::raw_dim) instead, e.g. + /// `Array::zeros(arr.raw_dim())`. + pub fn shape(&self) -> &[usize] { self.dim.slice() } - /// Return the strides of the array as a slice - pub fn strides(&self) -> &[Ixs] { + /// Return the strides of the array as a slice. + pub fn strides(&self) -> &[isize] { let s = self.strides.slice(); // reinterpret unsigned integer as signed unsafe { From 86f222054fb2e435393687483028923fad8d85b2 Mon Sep 17 00:00:00 2001 From: Jim Turner Date: Mon, 11 Mar 2019 17:43:40 -0400 Subject: [PATCH 2/2] Add example of .shape()/.raw_dim() --- src/impl_methods.rs | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/src/impl_methods.rs b/src/impl_methods.rs index 52b540f74..444d98525 100644 --- a/src/impl_methods.rs +++ b/src/impl_methods.rs @@ -102,18 +102,28 @@ where /// Return the shape of the array as a slice. /// - /// Note that you probably don't want to use this to create an - /// array of the same shape as another array because creating an - /// array with e.g. [`Array::zeros()`](ArrayBase::zeros) using a - /// shape of type `&[usize]` results in a dynamic-dimensional - /// array. For example, if `arr` is of type `Array`, then - /// `Array::zeros(arr.shape())` returns an instance of type - /// `Array`, not `Array`. - /// - /// If you want to create an array that has the same shape and - /// dimensionality as another array, use - /// [`.raw_dim()`](ArrayBase::raw_dim) instead, e.g. - /// `Array::zeros(arr.raw_dim())`. + /// Note that you probably don't want to use this to create an array of the + /// same shape as another array because creating an array with e.g. + /// [`Array::zeros()`](ArrayBase::zeros) using a shape of type `&[usize]` + /// results in a dynamic-dimensional array. If you want to create an array + /// that has the same shape and dimensionality as another array, use + /// [`.raw_dim()`](ArrayBase::raw_dim) instead: + /// + /// ```rust + /// use ndarray::{Array, Array2}; + /// + /// let a = Array2::::zeros((3, 4)); + /// let shape = a.shape(); + /// assert_eq!(shape, &[3, 4]); + /// + /// // Since `a.shape()` returned `&[usize]`, we get an `ArrayD` instance: + /// let b = Array::zeros(shape); + /// assert_eq!(a.clone().into_dyn(), b); + /// + /// // To get the same dimension type, use `.raw_dim()` instead: + /// let c = Array::zeros(a.raw_dim()); + /// assert_eq!(a, c); + /// ``` pub fn shape(&self) -> &[usize] { self.dim.slice() }