Introduce bounds check pixel get/get_mut

The intention here is to help the optimizer. For methods where access
out-of-bounds is not fatal the bounds checking code appears to be
repeated unnecessarily in many cases—once for a manual check to avoid
the panic and once in the impl in the path that would lead to such
panic.

This is backwards compatible in that the new methods are default
implemented on the traits. In the long term it seems nevertheless
advisable to flip this around and default implement the panicking method
instead. This would also improve possibilities for indexing and
adherence to the API guidelines.

Author: HeroicKatora

src/buffer.rs

@@ -775,6 +775,14 @@ where
         *self.get_pixel(x, y)
     }
 
+    fn opt_pixel(&self, x: u32, y: u32) -> Option<P> {
+        if let Some(idx) = self.pixel_indices(x, y) {
+            Some(*P::from_slice(&self.data[idx]))
+        } else {
+            None
+        }
+    }
+
     /// Returns the pixel located at (x, y), ignoring bounds checking.
     #[inline(always)]
     unsafe fn unsafe_get_pixel(&self, x: u32, y: u32) -> P {
@@ -799,6 +807,14 @@ where
         self.get_pixel_mut(x, y)
     }
 
+    fn opt_pixel_mut(&mut self, x: u32, y: u32) -> Option<&mut P> {
+        if let Some(idx) = self.pixel_indices(x, y) {
+            Some(P::from_slice_mut(&mut self.data[idx]))
+        } else {
+            None
+        }
+    }
+
     fn put_pixel(&mut self, x: u32, y: u32, pixel: P) {
         *self.get_pixel_mut(x, y) = pixel
     }

src/image.rs

@@ -583,6 +583,25 @@ pub trait GenericImageView {
     /// TODO: change this signature to &P
     fn get_pixel(&self, x: u32, y: u32) -> Self::Pixel;
 
+    /// Get the pixel value at (x, y) when in bounds.
+    ///
+    /// Return `Some(_)` with the pixel value if the coordinates are [`in_bounds`] and otherwise
+    /// returns `None`.
+    ///
+    /// This method can be overridden by image implementations to be more efficient than the manual
+    /// bounds check. In particular, `get_pixel` will often do its own bounds check and would
+    /// duplicate this prior step. The optimizer may not detect all of them.
+    ///
+    /// [`in_bounds`]: #method.in_bounds
+    // TODO: swap the default implementation to `get_pixel`.
+    fn opt_pixel(&self, x: u32, y: u32) -> Option<Self::Pixel> {
+        if self.in_bounds(x, y) {
+            Some(self.get_pixel(x, y))
+        } else {
+            None
+        }
+    }
+
     /// Returns the pixel located at (x, y)
     ///
     /// This function can be implemented in a way that ignores bounds checking.
@@ -629,6 +648,24 @@ pub trait GenericImage: GenericImageView {
     /// Panics if `(x, y)` is out of bounds.
     fn get_pixel_mut(&mut self, x: u32, y: u32) -> &mut Self::Pixel;
 
+    /// Gets a reference to the mutable pixel when location `(x, y)` is in bounds.
+    ///
+    /// Return `Some(_)` with the pixel value if the coordinates are [`in_bounds`] and otherwise
+    /// returns `None`.
+    ///
+    /// This method can be overridden by image implementations to be more efficient than the manual
+    /// bounds check. In particular, `get_pixel` will often do its own bounds check and would
+    /// duplicate this prior step. The optimizer may not detect all of them.
+    ///
+    /// [`in_bounds`]: trait.GenericImageView.html#method.in_bounds
+    fn opt_pixel_mut(&mut self, x: u32, y: u32) -> Option<&mut Self::Pixel> {
+        if self.in_bounds(x, y) {
+            Some(self.get_pixel_mut(x, y))
+        } else {
+            None
+        }
+    }
+
     /// Put a pixel at location (x, y)
     ///
     /// # Panics