Add .into_raw_vec_with_offset() and deprecate .into_raw_vec()

Provide a smoother transition by deprecating the old method and
introducing a new one.

Return Option<usize>, this makes the empty vector case stand out
as a separate case that needs to be handled.

Author: bluss

examples/sort-axis.rs

@@ -157,7 +157,7 @@ where D: Dimension
                 });
             debug_assert_eq!(result.len(), moved_elements);
             // forget the old elements but not the allocation
-            let mut old_storage = self.into_raw_vec().0;
+            let mut old_storage = self.into_raw_vec_and_offset().0;
             old_storage.set_len(0);
 
             // transfer ownership of the elements into the result

src/dimension/mod.rs

@@ -410,7 +410,7 @@ fn to_abs_slice(axis_len: usize, slice: Slice) -> (usize, usize, isize)
 }
 
 /// This function computes the offset from the lowest address element to the
-/// logically first element. The result is always >= 0.
+/// logically first element.
 pub fn offset_from_low_addr_ptr_to_logical_ptr<D: Dimension>(dim: &D, strides: &D) -> usize
 {
     let offset = izip!(dim.slice(), strides.slice()).fold(0, |_offset, (&d, &s)| {

src/impl_owned_array.rs

@@ -77,7 +77,7 @@ where D: Dimension
 
     /// Return a vector of the elements in the array, in the way they are
     /// stored internally, and the index in the vector corresponding to the
-    /// logically first element of the array (or `None` if the array is empty).
+    /// logically first element of the array (or 0 if the array is empty).
     ///
     /// If the array is in standard memory layout, the logical element order
     /// of the array (`.iter()` order) and of the returned vector will be the same.
@@ -92,7 +92,7 @@ where D: Dimension
     ///
     /// let shape = arr.shape().to_owned();
     /// let strides = arr.strides().to_owned();
-    /// let (v, offset) = arr.into_raw_vec();
+    /// let (v, offset) = arr.into_raw_vec_and_offset();
     ///
     /// assert_eq!(v, &[1., 2., 3., 4., 5., 6.]);
     /// assert_eq!(offset, Some(2));
@@ -124,7 +124,7 @@ where D: Dimension
     ///
     /// let shape = arr.shape().to_owned();
     /// let strides = arr.strides().to_owned();
-    /// let (v, offset) = arr.into_raw_vec();
+    /// let (v, offset) = arr.into_raw_vec_and_offset();
     ///
     /// assert_eq!(v, &[(), (), (), (), (), ()]);
     /// for row in 0..shape[0] {
@@ -138,11 +138,23 @@ where D: Dimension
     ///     }
     /// }
     /// ```
-    pub fn into_raw_vec(self) -> (Vec<A>, Option<usize>)
+    pub fn into_raw_vec_and_offset(self) -> (Vec<A>, Option<usize>)
     {
         let offset = self.offset_from_alloc_to_logical_ptr();
         (self.data.into_vec(), offset)
     }
+
+    /// Return a vector of the elements in the array, in the way they are
+    /// stored internally.
+    ///
+    /// Depending on slicing and strides, the logically first element of the
+    /// array can be located at an offset. Because of this, prefer to use
+    /// `.into_raw_vec_and_offset()` instead.
+    #[deprecated(note = "Use .into_raw_vec_and_offset() instead")]
+    pub fn into_raw_vec(self) -> Vec<A>
+    {
+        self.into_raw_vec_and_offset().0
+    }
 }
 
 /// Methods specific to `Array2`.

tests/array-construct.rs

@@ -19,9 +19,9 @@ fn test_from_shape_fn()
 fn test_dimension_zero()
 {
     let a: Array2<f32> = Array2::from(vec![[], [], []]);
-    assert_eq!(vec![0.; 0], a.into_raw_vec().0);
+    assert_eq!((vec![0.; 0], None), a.into_raw_vec_and_offset());
     let a: Array3<f32> = Array3::from(vec![[[]], [[]], [[]]]);
-    assert_eq!(vec![0.; 0], a.into_raw_vec().0);
+    assert_eq!((vec![0.; 0], None), a.into_raw_vec_and_offset());
 }
 
 #[test]

tests/array.rs

@@ -1157,7 +1157,10 @@ fn array0_into_scalar()
     // With this kind of setup, the `Array`'s pointer is not the same as the
     // underlying `Vec`'s pointer.
     let a: Array0<i32> = array![4, 5, 6, 7].index_axis_move(Axis(0), 2);
-    assert_ne!(a.as_ptr(), a.into_raw_vec().0.as_ptr());
+    let a_ptr = a.as_ptr();
+    let (raw_vec, offset) = a.into_raw_vec_and_offset();
+    assert_ne!(a_ptr, raw_vec.as_ptr());
+    assert_eq!(offset, Some(2));
     // `.into_scalar()` should still work correctly.
     let a: Array0<i32> = array![4, 5, 6, 7].index_axis_move(Axis(0), 2);
     assert_eq!(a.into_scalar(), 6);
@@ -1173,7 +1176,10 @@ fn array_view0_into_scalar()
     // With this kind of setup, the `Array`'s pointer is not the same as the
     // underlying `Vec`'s pointer.
     let a: Array0<i32> = array![4, 5, 6, 7].index_axis_move(Axis(0), 2);
-    assert_ne!(a.as_ptr(), a.into_raw_vec().0.as_ptr());
+    let a_ptr = a.as_ptr();
+    let (raw_vec, offset) = a.into_raw_vec_and_offset();
+    assert_ne!(a_ptr, raw_vec.as_ptr());
+    assert_eq!(offset, Some(2));
     // `.into_scalar()` should still work correctly.
     let a: Array0<i32> = array![4, 5, 6, 7].index_axis_move(Axis(0), 2);
     assert_eq!(a.view().into_scalar(), &6);
@@ -1189,7 +1195,7 @@ fn array_view_mut0_into_scalar()
     // With this kind of setup, the `Array`'s pointer is not the same as the
     // underlying `Vec`'s pointer.
     let a: Array0<i32> = array![4, 5, 6, 7].index_axis_move(Axis(0), 2);
-    assert_ne!(a.as_ptr(), a.into_raw_vec().0.as_ptr());
+    assert_ne!(a.as_ptr(), a.into_raw_vec_and_offset().0.as_ptr());
     // `.into_scalar()` should still work correctly.
     let mut a: Array0<i32> = array![4, 5, 6, 7].index_axis_move(Axis(0), 2);
     assert_eq!(a.view_mut().into_scalar(), &6);
@@ -1199,6 +1205,16 @@ fn array_view_mut0_into_scalar()
     assert_eq!(a.view_mut().into_scalar(), &());
 }
 
+#[test]
+fn array1_into_raw_vec()
+{
+    let data = vec![4, 5, 6, 7];
+    let array = Array::from(data.clone());
+    let (raw_vec, offset) = array.into_raw_vec_and_offset();
+    assert_eq!(data, raw_vec);
+    assert_eq!(offset, Some(0));
+}
+
 #[test]
 fn owned_array1()
 {