Add from_shape and deprecate from_dim_slice for ArrayView, ArrayViewMut

Author: bluss

src/impl_constructors.rs

@@ -15,106 +15,11 @@
 use libnum::{Zero, One, Float};
 
 use imp_prelude::*;
+use {Shape, StrideShape};
 use dimension;
 use linspace;
 use error::{self, ShapeError, ErrorKind};
 
-/// A contiguous array shape of n dimensions.
-///
-/// Either c- or f- memory ordered (*c* a.k.a *row major* is the default).
-#[derive(Copy, Clone, Debug)]
-pub struct Shape<D> {
-    dim: D,
-    is_c: bool,
-}
-
-/// An array shape of n dimensions c-order, f-order or custom strides.
-#[derive(Copy, Clone, Debug)]
-pub struct StrideShape<D> {
-    dim: D,
-    strides: D,
-    custom: bool,
-}
-
-/// A trait for `Shape` and `D where D: Dimension` that allows
-/// customizing the memory layout (strides) of an array shape.
-pub trait ShapeBuilder {
-    type Dim: Dimension;
-
-    fn f(self) -> Shape<Self::Dim>;
-    fn set_f(self, is_f: bool) -> Shape<Self::Dim>;
-    fn strides(self, strides: Self::Dim) -> StrideShape<Self::Dim>;
-}
-
-impl<D> From<D> for Shape<D>
-    where D: Dimension
-{
-    fn from(d: D) -> Self {
-        Shape {
-            dim: d,
-            is_c: true,
-        }
-    }
-}
-
-impl<D> From<D> for StrideShape<D>
-    where D: Dimension
-{
-    fn from(d: D) -> Self {
-        StrideShape {
-            strides: d.default_strides(),
-            dim: d,
-            custom: false,
-        }
-    }
-}
-
-impl<D> From<Shape<D>> for StrideShape<D>
-    where D: Dimension
-{
-    fn from(shape: Shape<D>) -> Self {
-        let d = shape.dim;
-        let st = if shape.is_c { d.default_strides() } else { d.fortran_strides() };
-        StrideShape {
-            strides: st,
-            dim: d,
-            custom: false,
-        }
-    }
-}
-
-impl<D> ShapeBuilder for D
-    where D: Dimension
-{
-    type Dim = D;
-    fn f(self) -> Shape<D> { self.set_f(true) }
-    fn set_f(self, is_f: bool) -> Shape<D> {
-        Shape::from(self).set_f(is_f)
-    }
-    fn strides(self, st: D) -> StrideShape<D> {
-        Shape::from(self).strides(st)
-    }
-}
-
-impl<D> ShapeBuilder for Shape<D>
-    where D: Dimension
-{
-    type Dim = D;
-    fn f(self) -> Self { self.set_f(true) }
-    fn set_f(mut self, is_f: bool) -> Self {
-        self.is_c = !is_f;
-        self
-    }
-    fn strides(self, st: D) -> StrideShape<D> {
-        StrideShape {
-            dim: self.dim,
-            strides: st,
-            custom: true,
-        }
-    }
-}
-
-
 /// Constructor methods for one-dimensional arrays.
 ///
 /// Note that the constructor methods apply to `OwnedArray` and `RcArray`,

src/impl_views.rs

@@ -10,6 +10,8 @@ use imp_prelude::*;
 use dimension::{self, stride_offset};
 use error::ShapeError;
 
+use StrideShape;
+
 /// # Methods for Array Views
 ///
 /// Methods for read-only array views `ArrayView<'a, A, D>`
@@ -21,17 +23,17 @@ impl<'a, A, D> ArrayBase<ViewRepr<&'a A>, D>
 {
     /// Create a read-only array view borrowing its data from a slice.
     ///
-    /// Checks whether `dim` and `strides` are compatible with the slice's
+    /// Checks whether `shape` are compatible with the slice's
     /// length, returning an `Err` if not compatible.
     ///
     /// ```
     /// use ndarray::ArrayView;
     /// use ndarray::arr3;
+    /// use ndarray::ShapeBuilder;
     ///
     /// let s = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
-    /// let a = ArrayView::from_slice_dim_stride((2, 3, 2),
-    ///                                          (1, 4, 2),
-    ///                                          &s).unwrap();
+    /// let a = ArrayView::from_shape((2, 3, 2).strides((1, 4, 2)),
+    ///                               &s).unwrap();
     ///
     /// assert!(
     ///     a == arr3(&[[[0, 2],
@@ -43,6 +45,22 @@ impl<'a, A, D> ArrayBase<ViewRepr<&'a A>, D>
     /// );
     /// assert!(a.strides() == &[1, 4, 2]);
     /// ```
+    pub fn from_shape<Sh>(shape: Sh, xs: &'a [A])
+        -> Result<Self, ShapeError>
+        where Sh: Into<StrideShape<D>>,
+    {
+        let shape = shape.into();
+        let dim = shape.dim;
+        let strides = shape.strides;
+        dimension::can_index_slice(xs, &dim, &strides).map(|_| {
+            unsafe {
+                Self::new_(xs.as_ptr(), dim, strides)
+            }
+        })
+    }
+
+    #[cfg_attr(has_deprecated, deprecated(note="Use from_shape instead."))]
+    /// ***Deprecated: Use from_shape instead***
     pub fn from_slice_dim_stride(dim: D, strides: D, xs: &'a [A])
         -> Result<Self, ShapeError>
     {
@@ -111,11 +129,11 @@ impl<'a, A, D> ArrayBase<ViewRepr<&'a mut A>, D>
     /// ```
     /// use ndarray::ArrayViewMut;
     /// use ndarray::arr3;
+    /// use ndarray::ShapeBuilder;
     ///
     /// let mut s = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12];
-    /// let mut a = ArrayViewMut::from_slice_dim_stride((2, 3, 2),
-    ///                                                 (1, 4, 2),
-    ///                                                 &mut s).unwrap();
+    /// let mut a = ArrayViewMut::from_shape((2, 3, 2).strides((1, 4, 2)),
+    ///                                      &mut s).unwrap();
     ///
     /// a[[0, 0, 0]] = 1;
     /// assert!(
@@ -128,6 +146,22 @@ impl<'a, A, D> ArrayBase<ViewRepr<&'a mut A>, D>
     /// );
     /// assert!(a.strides() == &[1, 4, 2]);
     /// ```
+    pub fn from_shape<Sh>(shape: Sh, xs: &'a mut [A])
+        -> Result<Self, ShapeError>
+        where Sh: Into<StrideShape<D>>,
+    {
+        let shape = shape.into();
+        let dim = shape.dim;
+        let strides = shape.strides;
+        dimension::can_index_slice(xs, &dim, &strides).map(|_| {
+            unsafe {
+                Self::new_(xs.as_mut_ptr(), dim, strides)
+            }
+        })
+    }
+
+    #[cfg_attr(has_deprecated, deprecated(note="Use from_shape instead."))]
+    /// ***Deprecated: Use from_shape instead***
     pub fn from_slice_dim_stride(dim: D, strides: D, xs: &'a mut [A])
         -> Result<Self, ShapeError>
     {

src/lib.rs

@@ -108,9 +108,7 @@ pub use arraytraits::AsArray;
 pub use linalg_traits::{LinalgScalar, NdFloat};
 pub use stacking::stack;
 
-pub use impl_constructors::{
-    ShapeBuilder, Shape, StrideShape,
-};
+pub use shape_builder::{ ShapeBuilder };
 
 mod arraytraits;
 #[cfg(feature = "serde")]
@@ -138,6 +136,7 @@ mod linspace;
 mod numeric_util;
 mod si;
 mod error;
+mod shape_builder;
 mod stacking;
 
 /// Implementation's prelude. Common types used everywhere.
@@ -701,3 +700,21 @@ enum ElementsRepr<S, C> {
     Slice(S),
     Counted(C),
 }
+
+
+/// A contiguous array shape of n dimensions.
+///
+/// Either c- or f- memory ordered (*c* a.k.a *row major* is the default).
+#[derive(Copy, Clone, Debug)]
+pub struct Shape<D> {
+    dim: D,
+    is_c: bool,
+}
+
+/// An array shape of n dimensions c-order, f-order or custom strides.
+#[derive(Copy, Clone, Debug)]
+pub struct StrideShape<D> {
+    dim: D,
+    strides: D,
+    custom: bool,
+}

src/shape_builder.rs

@@ -0,0 +1,86 @@
+
+use Dimension;
+use {Shape, StrideShape};
+
+/// A trait for `Shape` and `D where D: Dimension` that allows
+/// customizing the memory layout (strides) of an array shape.
+///
+/// This trait is used together with array constructor methods like
+/// `OwnedArray::from_shape_vec`.
+pub trait ShapeBuilder {
+    type Dim: Dimension;
+
+    fn f(self) -> Shape<Self::Dim>;
+    fn set_f(self, is_f: bool) -> Shape<Self::Dim>;
+    fn strides(self, strides: Self::Dim) -> StrideShape<Self::Dim>;
+}
+
+impl<D> From<D> for Shape<D>
+    where D: Dimension
+{
+    fn from(d: D) -> Self {
+        Shape {
+            dim: d,
+            is_c: true,
+        }
+    }
+}
+
+impl<D> From<D> for StrideShape<D>
+    where D: Dimension
+{
+    fn from(d: D) -> Self {
+        StrideShape {
+            strides: d.default_strides(),
+            dim: d,
+            custom: false,
+        }
+    }
+}
+
+impl<D> From<Shape<D>> for StrideShape<D>
+    where D: Dimension
+{
+    fn from(shape: Shape<D>) -> Self {
+        let d = shape.dim;
+        let st = if shape.is_c { d.default_strides() } else { d.fortran_strides() };
+        StrideShape {
+            strides: st,
+            dim: d,
+            custom: false,
+        }
+    }
+}
+
+impl<D> ShapeBuilder for D
+    where D: Dimension
+{
+    type Dim = D;
+    fn f(self) -> Shape<D> { self.set_f(true) }
+    fn set_f(self, is_f: bool) -> Shape<D> {
+        Shape::from(self).set_f(is_f)
+    }
+    fn strides(self, st: D) -> StrideShape<D> {
+        Shape::from(self).strides(st)
+    }
+}
+
+impl<D> ShapeBuilder for Shape<D>
+    where D: Dimension
+{
+    type Dim = D;
+    fn f(self) -> Self { self.set_f(true) }
+    fn set_f(mut self, is_f: bool) -> Self {
+        self.is_c = !is_f;
+        self
+    }
+    fn strides(self, st: D) -> StrideShape<D> {
+        StrideShape {
+            dim: self.dim,
+            strides: st,
+            custom: true,
+        }
+    }
+}
+
+