Add .last() and .last_mut() methods

src/impl_methods.rs

@@ -256,6 +256,19 @@ where
 
     /// Returns a reference to the first element of the array, or `None` if it
     /// is empty.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ndarray::Array3;
+    ///
+    /// let mut a = Array3::<f64>::zeros([3, 4, 2]);
+    /// a[[0, 0, 0]] = 42.;
+    /// assert_eq!(a.first(), Some(&42.));
+    ///
+    /// let b = Array3::<f64>::zeros([3, 0, 5]);
+    /// assert_eq!(b.first(), None);
+    /// ```
     pub fn first(&self) -> Option<&A>
     where
         S: Data,
@@ -269,6 +282,19 @@ where
 
     /// Returns a mutable reference to the first element of the array, or
     /// `None` if it is empty.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ndarray::Array3;
+    ///
+    /// let mut a = Array3::<f64>::zeros([3, 4, 2]);
+    /// *a.first_mut().unwrap() = 42.;
+    /// assert_eq!(a[[0, 0, 0]], 42.);
+    ///
+    /// let mut b = Array3::<f64>::zeros([3, 0, 5]);
+    /// assert_eq!(b.first_mut(), None);
+    /// ```
     pub fn first_mut(&mut self) -> Option<&mut A>
     where
         S: DataMut,
@@ -280,6 +306,66 @@ where
         }
     }
 
+    /// Returns a reference to the last element of the array, or `None` if it
+    /// is empty.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ndarray::Array3;
+    ///
+    /// let mut a = Array3::<f64>::zeros([3, 4, 2]);
+    /// a[[2, 3, 1]] = 42.;
+    /// assert_eq!(a.last(), Some(&42.));
+    ///
+    /// let b = Array3::<f64>::zeros([3, 0, 5]);
+    /// assert_eq!(b.last(), None);
+    /// ```
+    pub fn last(&self) -> Option<&A>
+    where
+        S: Data,
+    {
+        if self.is_empty() {
+            None
+        } else {
+            let mut index = self.raw_dim();
+            for ax in 0..index.ndim() {
+                index[ax] -= 1;
+            }
+            Some(unsafe { self.uget(index) })
+        }
+    }
+
+    /// Returns a mutable reference to the last element of the array, or `None`
+    /// if it is empty.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use ndarray::Array3;
+    ///
+    /// let mut a = Array3::<f64>::zeros([3, 4, 2]);
+    /// *a.last_mut().unwrap() = 42.;
+    /// assert_eq!(a[[2, 3, 1]], 42.);
+    ///
+    /// let mut b = Array3::<f64>::zeros([3, 0, 5]);
+    /// assert_eq!(b.last_mut(), None);
+    /// ```
+    pub fn last_mut(&mut self) -> Option<&mut A>
+    where
+        S: DataMut,
+    {
+        if self.is_empty() {
+            None
+        } else {
+            let mut index = self.raw_dim();
+            for ax in 0..index.ndim() {
+                index[ax] -= 1;
+            }
+            Some(unsafe { self.uget_mut(index) })
+        }
+    }
+
     /// Return an iterator of references to the elements of the array.
     ///
     /// Elements are visited in the *logical order* of the array, which