Merge #268

268: Remove try_ prefix. r=eldruin a=Dirbaio

This removes the `try_` prefix from all the trait method names, after discussion on issue #177 .

Co-authored-by: Dario Nieuwenhuis <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Changed
 - Swap PWM channel arguments to references
+- All trait methods have been renamed to remove the `try_` prefix (i.e. `try_send` -> `send`) for consistency.
 
 ## [v1.0.0-alpha.4] - 2020-11-11
 

src/adc.rs

@@ -73,7 +73,7 @@ pub trait Channel<ADC> {
 /// {
 ///    type Error = ();
 ///
-///    fn try_read(&mut self, pin: &mut PIN) -> nb::Result<WORD, Self::Error> {
+///    fn read(&mut self, pin: &mut PIN) -> nb::Result<WORD, Self::Error> {
 ///        let chan = 1 << pin.channel();
 ///        self.power_up();
 ///        let result = self.do_conversion(chan);
@@ -90,5 +90,5 @@ pub trait OneShot<ADC, Word, Pin: Channel<ADC>> {
     ///
     /// This method takes a `Pin` reference, as it is expected that the ADC will be able to sample
     /// whatever channel underlies the pin.
-    fn try_read(&mut self, pin: &mut Pin) -> nb::Result<Word, Self::Error>;
+    fn read(&mut self, pin: &mut Pin) -> nb::Result<Word, Self::Error>;
 }

src/blocking/delay.rs

@@ -16,7 +16,7 @@ pub trait DelayMs<UXX> {
     type Error;
 
     /// Pauses execution for `ms` milliseconds
-    fn try_delay_ms(&mut self, ms: UXX) -> Result<(), Self::Error>;
+    fn delay_ms(&mut self, ms: UXX) -> Result<(), Self::Error>;
 }
 
 /// Microsecond delay
@@ -28,5 +28,5 @@ pub trait DelayUs<UXX> {
     type Error;
 
     /// Pauses execution for `us` microseconds
-    fn try_delay_us(&mut self, us: UXX) -> Result<(), Self::Error>;
+    fn delay_us(&mut self, us: UXX) -> Result<(), Self::Error>;
 }

src/blocking/i2c.rs

@@ -30,7 +30,7 @@
 //! {
 //! #   type Error = ();
 //! #
-//!     fn try_write(&mut self, addr: u8, output: &[u8]) -> Result<(), Self::Error> {
+//!     fn write(&mut self, addr: u8, output: &[u8]) -> Result<(), Self::Error> {
 //!         // ...
 //! #       Ok(())
 //!     }
@@ -40,7 +40,7 @@
 //! {
 //! #   type Error = ();
 //! #
-//!     fn try_write(&mut self, addr: u16, output: &[u8]) -> Result<(), Self::Error> {
+//!     fn write(&mut self, addr: u16, output: &[u8]) -> Result<(), Self::Error> {
 //!         // ...
 //! #       Ok(())
 //!     }
@@ -66,7 +66,7 @@
 //!     pub fn read_temperature(&mut self) -> Result<u8, E> {
 //!         let mut temp = [0];
 //!         self.i2c
-//!             .try_write_read(ADDR, &[TEMP_REGISTER], &mut temp)
+//!             .write_read(ADDR, &[TEMP_REGISTER], &mut temp)
 //!             .and(Ok(temp[0]))
 //!     }
 //! }
@@ -89,7 +89,7 @@
 //!     pub fn read_temperature(&mut self) -> Result<u8, E> {
 //!         let mut temp = [0];
 //!         self.i2c
-//!             .try_write_read(ADDR, &[TEMP_REGISTER], &mut temp)
+//!             .write_read(ADDR, &[TEMP_REGISTER], &mut temp)
 //!             .and(Ok(temp[0]))
 //!     }
 //! }
@@ -135,7 +135,7 @@ pub trait Read<A: AddressMode = SevenBitAddress> {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master no acknowledge
     /// - `SP` = stop condition
-    fn try_read(&mut self, address: A, buffer: &mut [u8]) -> Result<(), Self::Error>;
+    fn read(&mut self, address: A, buffer: &mut [u8]) -> Result<(), Self::Error>;
 }
 
 /// Blocking write
@@ -159,7 +159,7 @@ pub trait Write<A: AddressMode = SevenBitAddress> {
     /// - `SAK` = slave acknowledge
     /// - `Bi` = ith byte of data
     /// - `SP` = stop condition
-    fn try_write(&mut self, address: A, bytes: &[u8]) -> Result<(), Self::Error>;
+    fn write(&mut self, address: A, bytes: &[u8]) -> Result<(), Self::Error>;
 }
 
 /// Blocking write (iterator version)
@@ -172,7 +172,7 @@ pub trait WriteIter<A: AddressMode = SevenBitAddress> {
     /// # I2C Events (contract)
     ///
     /// Same as `Write`
-    fn try_write_iter<B>(&mut self, address: A, bytes: B) -> Result<(), Self::Error>
+    fn write_iter<B>(&mut self, address: A, bytes: B) -> Result<(), Self::Error>
     where
         B: IntoIterator<Item = u8>;
 }
@@ -204,7 +204,7 @@ pub trait WriteRead<A: AddressMode = SevenBitAddress> {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master no acknowledge
     /// - `SP` = stop condition
-    fn try_write_read(
+    fn write_read(
         &mut self,
         address: A,
         bytes: &[u8],
@@ -223,7 +223,7 @@ pub trait WriteIterRead<A: AddressMode = SevenBitAddress> {
     /// # I2C Events (contract)
     ///
     /// Same as the `WriteRead` trait
-    fn try_write_iter_read<B>(
+    fn write_iter_read<B>(
         &mut self,
         address: A,
         bytes: B,
@@ -264,11 +264,8 @@ pub trait Transactional<A: AddressMode = SevenBitAddress> {
     /// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
     /// - `SR` = repeated start condition
     /// - `SP` = stop condition
-    fn try_exec<'a>(
-        &mut self,
-        address: A,
-        operations: &mut [Operation<'a>],
-    ) -> Result<(), Self::Error>;
+    fn exec<'a>(&mut self, address: A, operations: &mut [Operation<'a>])
+        -> Result<(), Self::Error>;
 }
 
 /// Transactional I2C interface (iterator version).
@@ -291,7 +288,7 @@ pub trait TransactionalIter<A: AddressMode = SevenBitAddress> {
     /// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
     /// - `SR` = repeated start condition
     /// - `SP` = stop condition
-    fn try_exec_iter<'a, O>(&mut self, address: A, operations: O) -> Result<(), Self::Error>
+    fn exec_iter<'a, O>(&mut self, address: A, operations: O) -> Result<(), Self::Error>
     where
         O: IntoIterator<Item = Operation<'a>>;
 }
@@ -310,7 +307,7 @@ pub trait TransactionalIter<A: AddressMode = SevenBitAddress> {
 ///
 /// impl i2c::Transactional<i2c::SevenBitAddress> for I2c1 {
 /// #    type Error = ();
-///     fn try_exec<'a>(
+///     fn exec<'a>(
 ///         &mut self,
 ///         address: i2c::SevenBitAddress,
 ///         operations: &mut [i2c::Operation<'a>],
@@ -327,7 +324,7 @@ pub trait TransactionalIter<A: AddressMode = SevenBitAddress> {
 /// use i2c::Write;
 ///
 /// let mut i2c1 = I2c1{};
-/// i2c1.try_write(0x01, &[0xAB, 0xCD]).unwrap();
+/// i2c1.write(0x01, &[0xAB, 0xCD]).unwrap();
 /// ```
 pub mod transactional {
     use super::{AddressMode, Operation, Read, Transactional, Write, WriteRead};
@@ -343,8 +340,8 @@ pub mod transactional {
     {
         type Error = E;
 
-        fn try_write(&mut self, address: A, bytes: &[u8]) -> Result<(), Self::Error> {
-            self.try_exec(address, &mut [Operation::Write(bytes)])
+        fn write(&mut self, address: A, bytes: &[u8]) -> Result<(), Self::Error> {
+            self.exec(address, &mut [Operation::Write(bytes)])
         }
     }
 
@@ -355,8 +352,8 @@ pub mod transactional {
     {
         type Error = E;
 
-        fn try_read(&mut self, address: A, buffer: &mut [u8]) -> Result<(), Self::Error> {
-            self.try_exec(address, &mut [Operation::Read(buffer)])
+        fn read(&mut self, address: A, buffer: &mut [u8]) -> Result<(), Self::Error> {
+            self.exec(address, &mut [Operation::Read(buffer)])
         }
     }
 
@@ -367,13 +364,13 @@ pub mod transactional {
     {
         type Error = E;
 
-        fn try_write_read(
+        fn write_read(
             &mut self,
             address: A,
             bytes: &[u8],
             buffer: &mut [u8],
         ) -> Result<(), Self::Error> {
-            self.try_exec(
+            self.exec(
                 address,
                 &mut [Operation::Write(bytes), Operation::Read(buffer)],
             )

src/blocking/rng.rs

@@ -12,5 +12,5 @@ pub trait Read {
     ///
     /// If this function returns an error, it is unspecified how many bytes it has read, but it
     /// will never read more than would be necessary to completely fill the buffer.
-    fn try_read(&mut self, buffer: &mut [u8]) -> Result<(), Self::Error>;
+    fn read(&mut self, buffer: &mut [u8]) -> Result<(), Self::Error>;
 }

src/blocking/serial.rs

@@ -10,13 +10,13 @@ pub trait Write<Word> {
     /// An implementation can choose to buffer the write, returning `Ok(())`
     /// after the complete slice has been written to a buffer, but before all
     /// words have been sent via the serial interface. To make sure that
-    /// everything has been sent, call [`try_bflush`] after this function returns.
+    /// everything has been sent, call [`bflush`] after this function returns.
     ///
-    /// [`try_bflush`]: #tymethod.bflush
-    fn try_bwrite_all(&mut self, buffer: &[Word]) -> Result<(), Self::Error>;
+    /// [`bflush`]: #tymethod.bflush
+    fn bwrite_all(&mut self, buffer: &[Word]) -> Result<(), Self::Error>;
 
     /// Block until the serial interface has sent all buffered words
-    fn try_bflush(&mut self) -> Result<(), Self::Error>;
+    fn bflush(&mut self) -> Result<(), Self::Error>;
 }
 
 /// Blocking serial write
@@ -38,16 +38,16 @@ pub mod write {
     {
         type Error = S::Error;
 
-        fn try_bwrite_all(&mut self, buffer: &[Word]) -> Result<(), Self::Error> {
+        fn bwrite_all(&mut self, buffer: &[Word]) -> Result<(), Self::Error> {
             for word in buffer {
-                nb::block!(self.try_write(word.clone()))?;
+                nb::block!(self.write(word.clone()))?;
             }
 
             Ok(())
         }
 
-        fn try_bflush(&mut self) -> Result<(), Self::Error> {
-            nb::block!(self.try_flush())?;
+        fn bflush(&mut self) -> Result<(), Self::Error> {
+            nb::block!(self.flush())?;
             Ok(())
         }
     }

src/blocking/spi.rs

@@ -6,7 +6,7 @@ pub trait Transfer<W> {
     type Error;
 
     /// Sends `words` to the slave. Returns the `words` received from the slave
-    fn try_transfer<'w>(&mut self, words: &'w mut [W]) -> Result<&'w [W], Self::Error>;
+    fn transfer<'w>(&mut self, words: &'w mut [W]) -> Result<&'w [W], Self::Error>;
 }
 
 /// Blocking write
@@ -15,7 +15,7 @@ pub trait Write<W> {
     type Error;
 
     /// Sends `words` to the slave, ignoring all the incoming words
-    fn try_write(&mut self, words: &[W]) -> Result<(), Self::Error>;
+    fn write(&mut self, words: &[W]) -> Result<(), Self::Error>;
 }
 
 /// Blocking write (iterator version)
@@ -24,7 +24,7 @@ pub trait WriteIter<W> {
     type Error;
 
     /// Sends `words` to the slave, ignoring all the incoming words
-    fn try_write_iter<WI>(&mut self, words: WI) -> Result<(), Self::Error>
+    fn write_iter<WI>(&mut self, words: WI) -> Result<(), Self::Error>
     where
         WI: IntoIterator<Item = W>;
 }
@@ -42,10 +42,10 @@ pub mod transfer {
     {
         type Error = S::Error;
 
-        fn try_transfer<'w>(&mut self, words: &'w mut [W]) -> Result<&'w [W], S::Error> {
+        fn transfer<'w>(&mut self, words: &'w mut [W]) -> Result<&'w [W], S::Error> {
             for word in words.iter_mut() {
-                nb::block!(self.try_send(word.clone()))?;
-                *word = nb::block!(self.try_read())?;
+                nb::block!(self.send(word.clone()))?;
+                *word = nb::block!(self.read())?;
             }
 
             Ok(words)
@@ -65,10 +65,10 @@ pub mod write {
     {
         type Error = S::Error;
 
-        fn try_write(&mut self, words: &[W]) -> Result<(), S::Error> {
+        fn write(&mut self, words: &[W]) -> Result<(), S::Error> {
             for word in words {
-                nb::block!(self.try_send(word.clone()))?;
-                nb::block!(self.try_read())?;
+                nb::block!(self.send(word.clone()))?;
+                nb::block!(self.read())?;
             }
 
             Ok(())
@@ -89,13 +89,13 @@ pub mod write_iter {
     {
         type Error = S::Error;
 
-        fn try_write_iter<WI>(&mut self, words: WI) -> Result<(), S::Error>
+        fn write_iter<WI>(&mut self, words: WI) -> Result<(), S::Error>
         where
             WI: IntoIterator<Item = W>,
         {
             for word in words.into_iter() {
-                nb::block!(self.try_send(word.clone()))?;
-                nb::block!(self.try_read())?;
+                nb::block!(self.send(word.clone()))?;
+                nb::block!(self.read())?;
             }
 
             Ok(())
@@ -121,7 +121,7 @@ pub trait Transactional<W: 'static> {
     type Error;
 
     /// Execute the provided transactions
-    fn try_exec<'a>(&mut self, operations: &mut [Operation<'a, W>]) -> Result<(), Self::Error>;
+    fn exec<'a>(&mut self, operations: &mut [Operation<'a, W>]) -> Result<(), Self::Error>;
 }
 
 /// Blocking transactional impl over spi::Write and spi::Transfer
@@ -139,11 +139,11 @@ pub mod transactional {
     {
         type Error = E;
 
-        fn try_exec<'a>(&mut self, operations: &mut [super::Operation<'a, W>]) -> Result<(), E> {
+        fn exec<'a>(&mut self, operations: &mut [super::Operation<'a, W>]) -> Result<(), E> {
             for op in operations {
                 match op {
-                    Operation::Write(w) => self.try_write(w)?,
-                    Operation::Transfer(t) => self.try_transfer(t).map(|_| ())?,
+                    Operation::Write(w) => self.write(w)?,
+                    Operation::Transfer(t) => self.transfer(t).map(|_| ())?,
                 }
             }
 

src/capture.rs

@@ -22,10 +22,10 @@ use nb;
 /// #       Capture1
 ///     };
 ///
-///     capture.try_set_resolution(1.ms()).unwrap();
+///     capture.set_resolution(1.ms()).unwrap();
 ///
-///     let before = block!(capture.try_capture(Channel::_1)).unwrap();
-///     let after = block!(capture.try_capture(Channel::_1)).unwrap();
+///     let before = block!(capture.capture(Channel::_1)).unwrap();
+///     let after = block!(capture.capture(Channel::_1)).unwrap();
 ///
 ///     let period = after.wrapping_sub(before);
 ///
@@ -43,11 +43,11 @@ use nb;
 /// #     type Capture = u16;
 /// #     type Channel = Channel;
 /// #     type Time = MilliSeconds;
-/// #     fn try_capture(&mut self, _: Channel) -> ::nb::Result<u16, Self::Error> { Ok(0) }
-/// #     fn try_disable(&mut self, _: Channel) -> Result<(), Self::Error> { unimplemented!() }
-/// #     fn try_enable(&mut self, _: Channel) -> Result<(), Self::Error> { unimplemented!() }
-/// #     fn try_get_resolution(&self) -> Result<MilliSeconds, Self::Error> { unimplemented!() }
-/// #     fn try_set_resolution<T>(&mut self, _: T) -> Result<(), Self::Error> where T: Into<MilliSeconds> { Ok(()) }
+/// #     fn capture(&mut self, _: Channel) -> ::nb::Result<u16, Self::Error> { Ok(0) }
+/// #     fn disable(&mut self, _: Channel) -> Result<(), Self::Error> { unimplemented!() }
+/// #     fn enable(&mut self, _: Channel) -> Result<(), Self::Error> { unimplemented!() }
+/// #     fn get_resolution(&self) -> Result<MilliSeconds, Self::Error> { unimplemented!() }
+/// #     fn set_resolution<T>(&mut self, _: T) -> Result<(), Self::Error> where T: Into<MilliSeconds> { Ok(()) }
 /// # }
 /// ```
 // unproven reason: pre-singletons API. With singletons a `CapturePin` (cf. `PwmPin`) trait seems more
@@ -78,19 +78,19 @@ pub trait Capture {
     ///
     /// NOTE that you must multiply the returned value by the *resolution* of
     /// this `Capture` interface to get a human time unit (e.g. seconds)
-    fn try_capture(&mut self, channel: Self::Channel) -> nb::Result<Self::Capture, Self::Error>;
+    fn capture(&mut self, channel: Self::Channel) -> nb::Result<Self::Capture, Self::Error>;
 
     /// Disables a capture `channel`
-    fn try_disable(&mut self, channel: Self::Channel) -> Result<(), Self::Error>;
+    fn disable(&mut self, channel: Self::Channel) -> Result<(), Self::Error>;
 
     /// Enables a capture `channel`
-    fn try_enable(&mut self, channel: Self::Channel) -> Result<(), Self::Error>;
+    fn enable(&mut self, channel: Self::Channel) -> Result<(), Self::Error>;
 
     /// Returns the current resolution
-    fn try_get_resolution(&self) -> Result<Self::Time, Self::Error>;
+    fn get_resolution(&self) -> Result<Self::Time, Self::Error>;
 
     /// Sets the resolution of the capture timer
-    fn try_set_resolution<R>(&mut self, resolution: R) -> Result<(), Self::Error>
+    fn set_resolution<R>(&mut self, resolution: R) -> Result<(), Self::Error>
     where
         R: Into<Self::Time>;
 }