Change NotContiguousError to AsSliceError

This is a breaking API change causing `PyArrayMethods::as_slice` to
become more accurate at reporting its failure reason.

Author: jakelishman

src/array.rs

@@ -26,7 +26,7 @@ use crate::cold;
 use crate::convert::{ArrayExt, IntoPyArray, NpyIndex, ToNpyDims, ToPyArray};
 use crate::dtype::{Element, PyArrayDescrMethods};
 use crate::error::{
-    BorrowError, DimensionalityError, FromVecError, IgnoreError, NotContiguousError, TypeError,
+    AsSliceError, BorrowError, DimensionalityError, FromVecError, IgnoreError, TypeError,
     DIMENSIONALITY_MISMATCH_ERR, MAX_DIMENSIONALITY_ERR,
 };
 use crate::npyffi::{self, npy_intp, NPY_ORDER, PY_ARRAY_API};
@@ -739,7 +739,7 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// or concurrently modified by Python or other native code.
     ///
     /// Please consider the safe alternative [`PyReadonlyArray::as_slice`].
-    unsafe fn as_slice(&self) -> Result<&[T], NotContiguousError>
+    unsafe fn as_slice(&self) -> Result<&[T], AsSliceError>
     where
         T: Element,
         D: Dimension,
@@ -749,10 +749,12 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
             // We can still produce a slice over zero objects regardless of whether
             // the underlying pointer is aligned or not.
             Ok(&[])
-        } else if self.is_aligned() && self.is_contiguous() {
-            Ok(slice::from_raw_parts(self.data(), len))
+        } else if !self.is_aligned() {
+            Err(AsSliceError::NotAligned)
+        } else if !self.is_contiguous() {
+            Err(AsSliceError::NotContiguous)
         } else {
-            Err(NotContiguousError)
+            Ok(slice::from_raw_parts(self.data(), len))
         }
     }
 
@@ -766,7 +768,7 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     ///
     /// Please consider the safe alternative [`PyReadwriteArray::as_slice_mut`].
     #[allow(clippy::mut_from_ref)]
-    unsafe fn as_slice_mut(&self) -> Result<&mut [T], NotContiguousError>
+    unsafe fn as_slice_mut(&self) -> Result<&mut [T], AsSliceError>
     where
         T: Element,
         D: Dimension,
@@ -776,10 +778,12 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
             // We can still produce a slice over zero objects regardless of whether
             // the underlying pointer is aligned or not.
             Ok(&mut [])
-        } else if self.is_aligned() && self.is_contiguous() {
-            Ok(slice::from_raw_parts_mut(self.data(), len))
+        } else if !self.is_aligned() {
+            Err(AsSliceError::NotAligned)
+        } else if !self.is_contiguous() {
+            Err(AsSliceError::NotContiguous)
         } else {
-            Err(NotContiguousError)
+            Ok(slice::from_raw_parts_mut(self.data(), len))
         }
     }
 
@@ -961,7 +965,7 @@ pub trait PyArrayMethods<'py, T, D>: PyUntypedArrayMethods<'py> {
     /// })
     /// # }
     /// ```
-    fn to_vec(&self) -> Result<Vec<T>, NotContiguousError>
+    fn to_vec(&self) -> Result<Vec<T>, AsSliceError>
     where
         T: Element,
         D: Dimension;
@@ -1468,7 +1472,7 @@ impl<'py, T, D> PyArrayMethods<'py, T, D> for Bound<'py, PyArray<T, D>> {
         unsafe { self.cast_unchecked() }
     }
 
-    fn to_vec(&self) -> Result<Vec<T>, NotContiguousError>
+    fn to_vec(&self) -> Result<Vec<T>, AsSliceError>
     where
         T: Element,
         D: Dimension,

src/borrow/mod.rs

@@ -180,7 +180,7 @@ use pyo3::{Borrowed, Bound, CastError, FromPyObject, PyAny, PyResult};
 use crate::array::{PyArray, PyArrayMethods};
 use crate::convert::NpyIndex;
 use crate::dtype::Element;
-use crate::error::{BorrowError, NotContiguousError};
+use crate::error::{BorrowError, AsSliceError};
 use crate::npyffi::flags;
 use crate::untyped_array::PyUntypedArrayMethods;
 
@@ -268,7 +268,7 @@ where
 
     /// Provide an immutable slice view of the interior of the NumPy array if it is contiguous.
     #[inline(always)]
-    pub fn as_slice(&self) -> Result<&[T], NotContiguousError> {
+    pub fn as_slice(&self) -> Result<&[T], AsSliceError> {
         // SAFETY: Global borrow flags ensure aliasing discipline.
         unsafe { self.array.as_slice() }
     }
@@ -511,7 +511,7 @@ where
 
     /// Provide a mutable slice view of the interior of the NumPy array if it is contiguous.
     #[inline(always)]
-    pub fn as_slice_mut(&mut self) -> Result<&mut [T], NotContiguousError> {
+    pub fn as_slice_mut(&mut self) -> Result<&mut [T], AsSliceError> {
         // SAFETY: Global borrow flags ensure aliasing discipline.
         unsafe { self.array.as_slice_mut() }
     }

src/error.rs

@@ -141,17 +141,27 @@ impl fmt::Display for FromVecError {
 
 impl_pyerr!(FromVecError);
 
-/// Represents that the given array is not contiguous.
+/// Represents that the given array is not compatible with viewing as a Rust slice.
+///
+/// If an array fails for more than one reason, it is not guaranteed which variant is returned.
 #[derive(Debug)]
-pub struct NotContiguousError;
+pub enum AsSliceError {
+    /// The array is not backed by an aligned pointer.
+    NotAligned,
+    /// The array is not contiguous in memory.
+    NotContiguous,
+}
 
-impl fmt::Display for NotContiguousError {
+impl fmt::Display for AsSliceError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "The given array is not contiguous")
+        match self {
+            Self::NotAligned => write!(f, "The given array is not aligned"),
+            Self::NotContiguous => write!(f, "The given array is not contiguous"),
+        }
     }
 }
 
-impl_pyerr!(NotContiguousError);
+impl_pyerr!(AsSliceError);
 
 /// Inidcates why borrowing an array failed.
 #[derive(Debug)]

src/lib.rs

@@ -106,7 +106,7 @@ pub use crate::borrow::{
 };
 pub use crate::convert::{IntoPyArray, NpyIndex, ToNpyDims, ToPyArray};
 pub use crate::dtype::{dtype, Complex32, Complex64, Element, PyArrayDescr, PyArrayDescrMethods};
-pub use crate::error::{BorrowError, FromVecError, NotContiguousError};
+pub use crate::error::{BorrowError, FromVecError, AsSliceError};
 pub use crate::npyffi::{PY_ARRAY_API, PY_UFUNC_API};
 pub use crate::strings::{PyFixedString, PyFixedUnicode};
 pub use crate::sum_products::{dot, einsum, inner};

tests/array.rs

@@ -196,7 +196,8 @@ fn as_slice() {
 
         let not_aligned = not_aligned_array(py);
         assert!(!not_aligned.is_aligned());
-        assert!(not_aligned.readonly().as_slice().is_err());
+        let err = not_aligned.readonly().as_slice().unwrap_err();
+        assert_eq!(err.to_string(), "The given array is not aligned");
 
         let misaligned_empty: Bound<'_, PyArray1<u16>> = {
             let arr = not_aligned_array(py);