Allow reclaiming display pins (#118)

* Changes based on discussion

* Add CHANGELOG entry

* Run cargo fmt

* Fix broken example

* Change method name to better reflect its purpose

* Remove rebase fail

* Commit suggestions

Co-authored-by: James Waples <[email protected]>

Co-authored-by: Dániel Buga <[email protected]>
Co-authored-by: James Waples <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -6,10 +6,15 @@
 
 ## [Unreleased] - ReleaseDate
 
+### Added
+
+- [#118](https://github.com/jamwaffles/ssd1306/pull/118) `DisplayModeTrait::into_properties()` new method that consumes the driver and returns the `DisplayProperties`
+
 ### Changed
 
 -**(breaking)** [#119](https://github.com/jamwaffles/ssd1306/pull/119) Remove `DisplayMode` and `RawMode`
 - [#120](https://github.com/jamwaffles/ssd1306/pull/120) Update to v0.4 [`display-interface`](https://crates.io/crates/display-interface)
+- **(breaking)** [#118](https://github.com/jamwaffles/ssd1306/pull/118) Change `release` method to return the display interface instead of the `DisplayProperties`.
 - **(breaking)** [#116](https://github.com/jamwaffles/ssd1306/pull/116) Replace custom I2C and SPI interfaces by generic [`display-interface`](https://crates.io/crates/display-interface)
 - **(breaking)** [#113](https://github.com/jamwaffles/ssd1306/pull/113) Removed public `send_bounded_data` from DisplayInterface and implementations
 

examples/noise_i2c.rs

@@ -1,4 +1,4 @@
-//! Send random raw data to the display, emulating an old untuned TV. This example `release()`s the
+//! Send random raw data to the display, emulating an old untuned TV. This example retrieves the
 //! underlying display properties struct and allows calling of the low-level `draw()` method,
 //! sending a 1024 byte buffer straight to the display.
 //!
@@ -65,7 +65,7 @@ fn main() -> ! {
     let mut disp: GraphicsMode<_> = Builder::new().connect(interface).into();
     disp.init().unwrap();
 
-    let mut props = disp.release();
+    let mut props = disp.into_properties();
 
     let mut buf = [0x00u8; 1024];
 

src/mode/displaymode.rs

@@ -3,10 +3,15 @@
 use crate::properties::DisplayProperties;
 
 /// Trait with core functionality for display mode switching
-pub trait DisplayModeTrait<DI> {
+pub trait DisplayModeTrait<DI>: Sized {
     /// Allocate all required data and initialise display for mode
     fn new(properties: DisplayProperties<DI>) -> Self;
 
-    /// Release resources for reuse with different mode
-    fn release(self) -> DisplayProperties<DI>;
+    /// Deconstruct object and retrieve DisplayProperties
+    fn into_properties(self) -> DisplayProperties<DI>;
+
+    /// Release display interface
+    fn release(self) -> DI {
+        self.into_properties().release()
+    }
 }

src/mode/graphics.rs

@@ -87,8 +87,8 @@ impl<DI> DisplayModeTrait<DI> for GraphicsMode<DI> {
         }
     }
 
-    /// Release all resources used by GraphicsMode
-    fn release(self) -> DisplayProperties<DI> {
+    /// Release display interface used by `GraphicsMode`
+    fn into_properties(self) -> DisplayProperties<DI> {
         self.properties
     }
 }

src/mode/terminal.rs

@@ -153,8 +153,8 @@ where
         }
     }
 
-    /// Release all resources used by TerminalMode
-    fn release(self) -> DisplayProperties<DI> {
+    /// Release display interface used by `TerminalMode`
+    fn into_properties(self) -> DisplayProperties<DI> {
         self.properties
     }
 }

src/properties.rs

@@ -17,10 +17,7 @@ pub struct DisplayProperties<DI> {
     addr_mode: AddrMode,
 }
 
-impl<DI> DisplayProperties<DI>
-where
-    DI: WriteOnlyDataCommand,
-{
+impl<DI> DisplayProperties<DI> {
     /// Create new DisplayProperties instance
     pub fn new(
         iface: DI,
@@ -48,7 +45,12 @@ where
     pub fn release(self) -> DI {
         self.iface
     }
+}
 
+impl<DI> DisplayProperties<DI>
+where
+    DI: WriteOnlyDataCommand,
+{
     /// Initialise the display in column mode (i.e. a byte walks down a column of 8 pixels) with
     /// column 0 on the left and column _(display_width - 1)_ on the right.
     pub fn init_column_mode(&mut self) -> Result<(), DisplayError> {