Update docs to show err in mutable

arrow-arith/src/arity.rs

@@ -243,6 +243,8 @@ where
 /// If the underlying buffers in `a` are not shared with other arrays,  mutates
 /// the underlying buffer in place, without allocating.
 ///
+/// If the underlying buffer in `a   are shared, returns Err(self)
+///
 /// Like [`unary`] the provided function is evaluated for every index, ignoring validity. This
 /// is beneficial when the cost of the operation is low compared to the cost of branching, and
 /// especially when the operation can be vectorised, however, requires `op` to be infallible
@@ -251,6 +253,7 @@ where
 /// # Errors
 ///
 /// * if the arrays have different lengths.
+/// * If the array is not mutable.
 ///
 /// # See Also
 ///

arrow-array/src/array/primitive_array.rs

@@ -484,13 +484,13 @@ pub use crate::types::ArrowPrimitiveType;
 /// # Example: Get a `PrimitiveArray` from an [`ArrayRef`]
 /// ```
 /// # use std::sync::Arc;
-/// # use arrow_array::{Array, ArrayRef, Float32Array, PrimitiveArray};
+/// # use arrow_array::{Array, cast::AsArray, ArrayRef, Float32Array, PrimitiveArray};
 /// # use arrow_array::types::{Float32Type};
 /// # use arrow_schema::DataType;
 /// # let array: ArrayRef =  Arc::new(Float32Array::from(vec![1.2, 2.3]));
 /// // will panic if the array is not a Float32Array
 /// assert_eq!(&DataType::Float32, array.data_type());
-/// let f32_array  = PrimitiveArray::<Float32Type>::from(array.into_data());
+/// let f32_array: Float32Array  = array.as_primitive().clone();
 /// assert_eq!(f32_array, Float32Array::from(vec![1.2, 2.3]));
 /// ```
 pub struct PrimitiveArray<T: ArrowPrimitiveType> {
@@ -798,6 +798,8 @@ impl<T: ArrowPrimitiveType> PrimitiveArray<T> {
     /// If the underlying buffers are not shared with other arrays,  mutates the
     /// underlying buffer in place, without allocating.
     ///
+    /// If the underlying buffer is shared, returns Err(self)
+    ///
     /// # Null Handling
     ///
     /// See [`Self::unary`] for more information on null handling.
@@ -819,16 +821,20 @@ impl<T: ArrowPrimitiveType> PrimitiveArray<T> {
     ///
     /// ```rust
     /// # use std::sync::Arc;
-    /// # use arrow_array::{Array, ArrayRef, Int32Array, PrimitiveArray, types::Int32Type};
+    /// # use arrow_array::{Array, cast::AsArray, ArrayRef, Int32Array, PrimitiveArray, types::Int32Type};
     /// # let array: ArrayRef = Arc::new(Int32Array::from(vec![Some(5), Some(7), None]));
     /// // Convert to Int32Array (panic's if array.data_type is not Int32)
-    /// let array = PrimitiveArray::<Int32Type>::from(array.into_data());
-    /// // Apply x*2+1 to the data in place, no allocations if
-    /// // there are no other references to the underlying buffer
-    /// // will create a new buffer if there are references.
-    /// let c = array.unary_mut(|x| x * 2 + 1).unwrap();
+    /// let a = array.as_primitive::<Int32Type>().clone();
+    /// // Try to apply x*2+1 to the data in place, fails because array is still shared
+    /// a.unary_mut(|x| x * 2 + 1).unwrap_err();
+    /// // Try again, this time dropping the last remaining reference
+    /// let a = array.as_primitive::<Int32Type>().clone();
+    /// drop(array);
+    /// // Now we can apply the operation in place
+    /// let c = a.unary_mut(|x| x * 2 + 1).unwrap();
     /// assert_eq!(c, Int32Array::from(vec![Some(11), Some(15), None]));
     /// ```
+
     pub fn unary_mut<F>(self, op: F) -> Result<PrimitiveArray<T>, PrimitiveArray<T>>
     where
         F: Fn(T::Native) -> T::Native,