Add DataRaw and DataRawMut traits

Author: jturner314

src/data_traits.rs

@@ -22,44 +22,89 @@ use {
 
 /// Array representation trait.
 ///
-/// ***Note:*** `Data` is not an extension interface at this point.
+/// For an array that meets the invariants of the `ArrayBase` type. This trait
+/// does not imply any ownership or lifetime; pointers to elements in the array
+/// may not be safe to dereference.
+///
+/// ***Note:*** `DataRaw` is not an extension interface at this point.
 /// Traits in Rust can serve many different roles. This trait is public because
 /// it is used as a bound on public methods.
-pub unsafe trait Data : Sized {
+pub unsafe trait DataRaw : Sized {
     /// The array element type.
     type Elem;
 
     #[doc(hidden)]
     // This method is only used for debugging
-    fn _data_slice(&self) -> &[Self::Elem];
+    fn _data_slice(&self) -> Option<&[Self::Elem]>;
+
+    private_decl!{}
+}
+
+/// Array representation trait.
+///
+/// For an array with writable elements.
+///
+/// ***Internal trait, see `DataRaw`.***
+pub unsafe trait DataRawMut : DataRaw {
+    /// If possible, ensures that the array has unique access to its data.
+    ///
+    /// If `Self` provides safe mutable access to array elements, then it
+    /// **must** panic or ensure that the data is unique.
+    #[doc(hidden)]
+    fn try_ensure_unique<D>(&mut ArrayBase<Self, D>)
+    where Self: Sized,
+          D: Dimension;
 
+    /// If possible, returns whether the array has unique access to its data.
+    ///
+    /// If `Self` provides safe mutable access to array elements, then it
+    /// **must** return `Some(_)`.
+    #[doc(hidden)]
+    fn try_is_unique(&mut self) -> Option<bool>;
+}
+
+/// Array representation trait.
+///
+/// For an array with elements that can be accessed with safe code.
+///
+/// ***Internal trait, see `DataRaw`.***
+pub unsafe trait Data : DataRaw {
     /// Converts the array to a uniquely owned array, cloning elements if necessary.
     #[doc(hidden)]
     fn into_owned<D>(self_: ArrayBase<Self, D>) -> ArrayBase<OwnedRepr<Self::Elem>, D>
     where
         Self::Elem: Clone,
         D: Dimension;
-
-    private_decl!{}
 }
 
 /// Array representation trait.
 ///
-/// For an array with writable elements.
+/// For an array with writable elements that can be accessed with safe code.
 ///
 /// ***Internal trait, see `Data`.***
-pub unsafe trait DataMut : Data {
+//
+// # For implementers
+//
+// If you implement the `DataMut` trait, you are guaranteeing that the
+// `DataRawMut::try_ensure_unique` implementation always panics or ensures that
+// the data is unique. You are also guaranteeing that `try_is_unique` always
+// returns `Some(_)`.
+pub unsafe trait DataMut : Data + DataRawMut {
+    /// Ensures that the array has unique access to its data.
     #[doc(hidden)]
     #[inline]
-    fn ensure_unique<D>(&mut ArrayBase<Self, D>)
-        where Self: Sized,
-              D: Dimension
-    { }
+    fn ensure_unique<D>(self_: &mut ArrayBase<Self, D>)
+    where Self: Sized,
+          D: Dimension
+    {
+        Self::try_ensure_unique(self_)
+    }
 
+    /// Returns whether the array has unique access to its data.
     #[doc(hidden)]
     #[inline]
     fn is_unique(&mut self) -> bool {
-        true
+        self.try_is_unique().unwrap()
     }
 }
 
@@ -81,33 +126,20 @@ pub unsafe trait DataClone : Data {
     }
 }
 
-unsafe impl<A> Data for OwnedArcRepr<A> {
+unsafe impl<A> DataRaw for OwnedArcRepr<A> {
     type Elem = A;
-    fn _data_slice(&self) -> &[A] {
-        &self.0
-    }
-    fn into_owned<D>(mut self_: ArrayBase<Self, D>) -> ArrayBase<OwnedRepr<Self::Elem>, D>
-    where
-        A: Clone,
-        D: Dimension,
-    {
-        Self::ensure_unique(&mut self_);
-        let data = OwnedRepr(Arc::try_unwrap(self_.data.0).ok().unwrap());
-        ArrayBase {
-            data: data,
-            ptr: self_.ptr,
-            dim: self_.dim,
-            strides: self_.strides,
-        }
+    fn _data_slice(&self) -> Option<&[A]> {
+        Some(&self.0)
     }
     private_impl!{}
 }
 
 // NOTE: Copy on write
-unsafe impl<A> DataMut for OwnedArcRepr<A>
-    where A: Clone
+unsafe impl<A> DataRawMut for OwnedArcRepr<A>
+where
+    A: Clone,
 {
-    fn ensure_unique<D>(self_: &mut ArrayBase<Self, D>)
+    fn try_ensure_unique<D>(self_: &mut ArrayBase<Self, D>)
         where Self: Sized,
               D: Dimension
     {
@@ -136,23 +168,59 @@ unsafe impl<A> DataMut for OwnedArcRepr<A>
         }
     }
 
-    fn is_unique(&mut self) -> bool {
-        Arc::get_mut(&mut self.0).is_some()
+    fn try_is_unique(&mut self) -> Option<bool> {
+        Some(Arc::get_mut(&mut self.0).is_some())
+    }
+}
+
+unsafe impl<A> Data for OwnedArcRepr<A> {
+    fn into_owned<D>(mut self_: ArrayBase<Self, D>) -> ArrayBase<OwnedRepr<Self::Elem>, D>
+    where
+        A: Clone,
+        D: Dimension,
+    {
+        Self::ensure_unique(&mut self_);
+        let data = OwnedRepr(Arc::try_unwrap(self_.data.0).ok().unwrap());
+        ArrayBase {
+            data: data,
+            ptr: self_.ptr,
+            dim: self_.dim,
+            strides: self_.strides,
+        }
     }
 }
 
+unsafe impl<A> DataMut for OwnedArcRepr<A> where A: Clone {}
+
 unsafe impl<A> DataClone for OwnedArcRepr<A> {
     unsafe fn clone_with_ptr(&self, ptr: *mut Self::Elem) -> (Self, *mut Self::Elem) {
         // pointer is preserved
         (self.clone(), ptr)
     }
 }
 
-unsafe impl<A> Data for OwnedRepr<A> {
+unsafe impl<A> DataRaw for OwnedRepr<A> {
     type Elem = A;
-    fn _data_slice(&self) -> &[A] {
-        &self.0
+    fn _data_slice(&self) -> Option<&[A]> {
+        Some(&self.0)
+    }
+    private_impl!{}
+}
+
+unsafe impl<A> DataRawMut for OwnedRepr<A> {
+    #[inline]
+    fn try_ensure_unique<D>(_: &mut ArrayBase<Self, D>)
+    where Self: Sized,
+          D: Dimension
+    {}
+
+    #[inline]
+    fn try_is_unique(&mut self) -> Option<bool> {
+        Some(true)
     }
+}
+
+unsafe impl<A> Data for OwnedRepr<A> {
     #[inline]
     fn into_owned<D>(self_: ArrayBase<Self, D>) -> ArrayBase<OwnedRepr<Self::Elem>, D>
     where
@@ -161,7 +229,6 @@ unsafe impl<A> Data for OwnedRepr<A> {
     {
         self_
     }
-    private_impl!{}
 }
 
 unsafe impl<A> DataMut for OwnedRepr<A> { }
@@ -192,19 +259,22 @@ unsafe impl<A> DataClone for OwnedRepr<A>
     }
 }
 
-unsafe impl<'a, A> Data for ViewRepr<&'a A> {
+unsafe impl<'a, A> DataRaw for ViewRepr<&'a A> {
     type Elem = A;
-    fn _data_slice(&self) -> &[A] {
-        &[]
+    fn _data_slice(&self) -> Option<&[A]> {
+        None
     }
+    private_impl!{}
+}
+
+unsafe impl<'a, A> Data for ViewRepr<&'a A> {
     fn into_owned<D>(self_: ArrayBase<Self, D>) -> ArrayBase<OwnedRepr<Self::Elem>, D>
     where
         Self::Elem: Clone,
         D: Dimension,
     {
         self_.to_owned()
     }
-    private_impl!{}
 }
 
 unsafe impl<'a, A> DataClone for ViewRepr<&'a A> {
@@ -213,19 +283,34 @@ unsafe impl<'a, A> DataClone for ViewRepr<&'a A> {
     }
 }
 
-unsafe impl<'a, A> Data for ViewRepr<&'a mut A> {
+unsafe impl<'a, A> DataRaw for ViewRepr<&'a mut A> {
     type Elem = A;
-    fn _data_slice(&self) -> &[A] {
-        &[]
+    fn _data_slice(&self) -> Option<&[A]> {
+        None
     }
+    private_impl!{}
+}
+
+unsafe impl<'a, A> DataRawMut for ViewRepr<&'a mut A> {
+    #[inline]
+    fn try_ensure_unique<D>(_: &mut ArrayBase<Self, D>)
+    where Self: Sized,
+          D: Dimension {}
+
+    #[inline]
+    fn try_is_unique(&mut self) -> Option<bool> {
+        Some(true)
+    }
+}
+
+unsafe impl<'a, A> Data for ViewRepr<&'a mut A> {
     fn into_owned<D>(self_: ArrayBase<Self, D>) -> ArrayBase<OwnedRepr<Self::Elem>, D>
     where
         Self::Elem: Clone,
         D: Dimension,
     {
         self_.to_owned()
     }
-    private_impl!{}
 }
 
 unsafe impl<'a, A> DataMut for ViewRepr<&'a mut A> { }

src/impl_methods.rs

@@ -1619,16 +1619,19 @@ impl<A, S, D> ArrayBase<S, D> where S: Data<Elem=A>, D: Dimension
     }
 
     fn pointer_is_inbounds(&self) -> bool {
-        let slc = self.data._data_slice();
-        if slc.is_empty() {
-            // special case for data-less views
-            return true;
+        match self.data._data_slice() {
+            None => {
+                // special case for non-owned views
+                true
+            }
+            Some(slc) => {
+                let ptr = slc.as_ptr() as *mut A;
+                let end = unsafe {
+                    ptr.offset(slc.len() as isize)
+                };
+                self.ptr >= ptr && self.ptr <= end
+            }
         }
-        let ptr = slc.as_ptr() as *mut A;
-        let end = unsafe {
-            ptr.offset(slc.len() as isize)
-        };
-        self.ptr >= ptr && self.ptr <= end
     }
 
     /// Perform an elementwise assigment to `self` from `rhs`.

src/lib.rs

@@ -152,6 +152,8 @@ mod data_traits;
 pub use aliases::*;
 
 pub use data_traits::{
+    DataRaw,
+    DataRawMut,
     Data,
     DataMut,
     DataOwned,
@@ -193,6 +195,8 @@ mod imp_prelude {
     pub use ArcArray;
     pub use {
         RemoveAxis,
+        DataRaw,
+        DataRawMut,
         Data,
         DataMut,
         DataOwned,
@@ -1024,7 +1028,7 @@ pub type Ixs = isize;
 //
 // [`.offset()`]: https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.offset-1
 pub struct ArrayBase<S, D>
-    where S: Data
+    where S: DataRaw
 {
     /// Data buffer / ownership information. (If owned, contains the data
     /// buffer; if borrowed, contains the lifetime and mutability.)