From 78a4d4dbcfaa41930248b6def97c2f125d03ecfd Mon Sep 17 00:00:00 2001
From: Vinzenz Schroeter <vinzenz.f.s@gmail.com>
Date: Tue, 15 Oct 2024 21:32:37 +0200
Subject: [PATCH] add Brightness::saturating_from

---
 .../servicepoint/examples/brightness_tester.rs  |  5 +++--
 crates/servicepoint/src/brightness.rs           | 17 +++++++++++++++++
 crates/servicepoint/src/primitive_grid.rs       | 12 ++++++++++++
 .../src/brightness_grid.rs                      |  7 +------
 4 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/crates/servicepoint/examples/brightness_tester.rs b/crates/servicepoint/examples/brightness_tester.rs
index 16fbf61..09e1ed6 100644
--- a/crates/servicepoint/examples/brightness_tester.rs
+++ b/crates/servicepoint/examples/brightness_tester.rs
@@ -25,10 +25,11 @@ fn main() {
     );
     connection.send(command).expect("send failed");
 
-    let max_brightness = usize::from(u8::from(Brightness::MAX));
+    let max_brightness: u8 = Brightness::MAX.into();
     let mut brightnesses = BrightnessGrid::new(TILE_WIDTH, TILE_HEIGHT);
     for (index, byte) in brightnesses.data_ref_mut().iter_mut().enumerate() {
-        *byte = Brightness::try_from((index % max_brightness) as u8).unwrap();
+        let level = index as u8 % max_brightness;
+        *byte = Brightness::try_from(level).unwrap();
     }
 
     connection
diff --git a/crates/servicepoint/src/brightness.rs b/crates/servicepoint/src/brightness.rs
index ad07aa6..e5a82b3 100644
--- a/crates/servicepoint/src/brightness.rs
+++ b/crates/servicepoint/src/brightness.rs
@@ -60,6 +60,17 @@ impl Brightness {
     pub const MAX: Brightness = Brightness(11);
     /// lowest possible brightness value, 0
     pub const MIN: Brightness = Brightness(0);
+
+    /// Create a brightness value without returning an error for brightnesses above [Brightness::MAX].
+    ///
+    /// returns: the specified value as a [Brightness], or [Brightness::MAX].
+    pub fn saturating_from(value: u8) -> Brightness {
+        if value > Brightness::MAX.into() {
+            Brightness::MAX
+        } else {
+            Brightness(value)
+        }
+    }
 }
 
 impl Default for Brightness {
@@ -138,4 +149,10 @@ mod tests {
         let actual = PrimitiveGrid::from(&grid);
         assert_eq!(actual.data_ref(), &[11, 0, 11, 11]);
     }
+
+    #[test]
+    fn saturating_convert() {
+        assert_eq!(Brightness::MAX, Brightness::saturating_from(100));
+        assert_eq!(Brightness(5), Brightness::saturating_from(5));
+    }
 }
diff --git a/crates/servicepoint/src/primitive_grid.rs b/crates/servicepoint/src/primitive_grid.rs
index f58c44c..69dcf0f 100644
--- a/crates/servicepoint/src/primitive_grid.rs
+++ b/crates/servicepoint/src/primitive_grid.rs
@@ -114,6 +114,18 @@ impl<T: PrimitiveGridType> PrimitiveGrid<T> {
     /// Convert between PrimitiveGrid types.
     ///
     /// See also [Iterator::map].
+    ///
+    /// # Examples
+    ///
+    /// Use logic written for u8s and then convert to [Brightness] values for sending in a [Command].
+    /// ```
+    /// # fn foo(grid: &mut PrimitiveGrid<u8>) {}
+    /// # use servicepoint::{Brightness, BrightnessGrid, Command, Origin, PrimitiveGrid, TILE_HEIGHT, TILE_WIDTH};
+    /// let mut grid: PrimitiveGrid<u8> = PrimitiveGrid::new(TILE_WIDTH, TILE_HEIGHT);
+    /// foo(&mut grid);
+    /// let grid: BrightnessGrid = grid.map(Brightness::saturating_from);
+    /// let command = Command::CharBrightness(Origin::ZERO, grid);
+    /// ```
     pub fn map<TConverted, F>(&self, f: F) -> PrimitiveGrid<TConverted>
     where
         TConverted: PrimitiveGridType,
diff --git a/crates/servicepoint_binding_c/src/brightness_grid.rs b/crates/servicepoint_binding_c/src/brightness_grid.rs
index db44687..c1dc186 100644
--- a/crates/servicepoint_binding_c/src/brightness_grid.rs
+++ b/crates/servicepoint_binding_c/src/brightness_grid.rs
@@ -21,14 +21,9 @@ use std::intrinsics::transmute;
 /// SPCommand command = sp_command_char_brightness(grid);
 /// sp_connection_free(connection);
 /// ```
+#[derive(Clone)]
 pub struct SPBrightnessGrid(pub(crate) servicepoint::BrightnessGrid);
 
-impl Clone for SPBrightnessGrid {
-    fn clone(&self) -> Self {
-        SPBrightnessGrid(self.0.clone())
-    }
-}
-
 /// Creates a new [SPBrightnessGrid] with the specified dimensions.
 ///
 /// returns: [SPBrightnessGrid] initialized to 0. Will never return NULL.