Deprecate Toggle use Switch

Author: Sh3Rm4n

CHANGELOG.md

@@ -19,6 +19,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Update `stm32f3` pac to v0.15.1 ([#335])
 - Update `bxcan` pac to v0.7.0 ([#335])
 - The MSRV was bumped to 1.59 ([#335])
+- Deprecate `Toggle` enum and use `Switch` instead for better naming purposes
+  ([#334])
+  - Add `impl From<Toggle> for Switch` to reduce churn.
 
 ## [v0.9.1] - 2022-09-07
 
@@ -571,6 +574,7 @@ let clocks = rcc
 [filter]: https://defmt.ferrous-systems.com/filtering.html
 
 [#335]: https://github.com/stm32-rs/stm32f3xx-hal/pull/335
+[#334]: https://github.com/stm32-rs/stm32f3xx-hal/pull/334
 [#322]: https://github.com/stm32-rs/stm32f3xx-hal/pull/322
 [#318]: https://github.com/stm32-rs/stm32f3xx-hal/pull/318
 [#317]: https://github.com/stm32-rs/stm32f3xx-hal/pull/317

examples/serial_echo_rtic.rs

@@ -19,7 +19,7 @@ mod app {
         pac,
         prelude::*,
         serial::{Event, Serial},
-        Toggle,
+        Switch,
     };
     use systick_monotonic::*;
 
@@ -81,7 +81,7 @@ mod app {
         pins.1.internal_pull_up(&mut gpioa.pupdr, true);
         let mut serial: SerialType =
             Serial::new(cx.device.USART1, pins, 19200.Bd(), clocks, &mut rcc.apb2);
-        serial.configure_interrupt(Event::ReceiveDataRegisterNotEmpty, Toggle::On);
+        serial.configure_interrupt(Event::ReceiveDataRegisterNotEmpty, Switch::On);
 
         rprintln!("post init");
 
@@ -100,12 +100,12 @@ mod app {
 
         if serial.is_event_triggered(Event::ReceiveDataRegisterNotEmpty) {
             dir.set_high().unwrap();
-            serial.configure_interrupt(Event::ReceiveDataRegisterNotEmpty, Toggle::Off);
+            serial.configure_interrupt(Event::ReceiveDataRegisterNotEmpty, Switch::Off);
             match serial.read() {
                 Ok(byte) => {
                     serial.write(byte).unwrap();
                     rprintln!("{:?}", char::from_u32(byte.into()).unwrap_or('?'));
-                    serial.configure_interrupt(Event::TransmissionComplete, Toggle::On);
+                    serial.configure_interrupt(Event::TransmissionComplete, Switch::On);
                 }
                 Err(_error) => rprintln!("irq error"),
             };

src/adc.rs

@@ -30,7 +30,7 @@ use crate::{
     pac::{self, adc1, Interrupt},
     rcc::{Clocks, Enable, AHB},
     time::{duration::Microseconds, fixed_point::FixedPoint, rate::Hertz},
-    Toggle,
+    Switch,
 };
 
 use crate::pac::{adc1_2, adc1_2::ccr::CKMODE_A};
@@ -493,7 +493,7 @@ where
         // TODO(Sh3Rm4n): Would about concurrent calibrations between related ADCs?
         // int_ref: &mut VoltageInternalReference<ADC>,
     ) {
-        self.configure_voltage_regulator(Toggle::On, clocks);
+        self.configure_voltage_regulator(Switch::On, clocks);
 
         self.reg
             .cr
@@ -512,21 +512,21 @@ where
         asm::delay(cpu_cycles);
 
         // When the internal voltage regulator is disabled, the internal analog calibration is kept
-        self.configure_voltage_regulator(Toggle::Off, clocks);
+        self.configure_voltage_regulator(Switch::Off, clocks);
     }
 
     /// Enable the interal voltage generator Blocks until regulator is enabled.
-    fn configure_voltage_regulator(&mut self, toggle: impl Into<Toggle>, clocks: &Clocks) {
+    fn configure_voltage_regulator(&mut self, toggle: impl Into<Switch>, clocks: &Clocks) {
         let already_on = self.reg.cr.read().advregen().is_enabled();
         let toggle = toggle.into();
         self.reg.cr.modify(|_, w| w.advregen().intermediate());
         self.reg.cr.modify(|_, w| {
             w.advregen().variant(match toggle {
-                Toggle::On => adc1::cr::ADVREGEN_A::Enabled,
-                Toggle::Off => adc1::cr::ADVREGEN_A::Disabled,
+                Switch::On => adc1::cr::ADVREGEN_A::Enabled,
+                Switch::Off => adc1::cr::ADVREGEN_A::Disabled,
             })
         });
-        if toggle == Toggle::On && !already_on {
+        if toggle == Switch::On && !already_on {
             let wait = MAX_ADVREGEN_STARTUP.integer()
                 * clocks.sysclk().integer()
                 * <Microseconds as FixedPoint>::SCALING_FACTOR;
@@ -1103,20 +1103,20 @@ where
     /// Enable the interrupt for the specified [`Event`].
     #[inline]
     pub fn enable_interrupt(&mut self, event: Event) {
-        self.configure_interrupt(event, Toggle::On);
+        self.configure_interrupt(event, Switch::On);
     }
 
     /// Disable the interrupt for the specified [`Event`].
     #[inline]
     pub fn disable_interrupt(&mut self, event: Event) {
-        self.configure_interrupt(event, Toggle::Off);
+        self.configure_interrupt(event, Switch::Off);
     }
 
     /// Enable or disable the interrupt for the specified [`Event`].
     #[inline]
-    pub fn configure_interrupt(&mut self, event: Event, enable: impl Into<Toggle>) {
-        // Do a round way trip to be convert Into<Toggle> -> bool
-        let enable: Toggle = enable.into();
+    pub fn configure_interrupt(&mut self, event: Event, enable: impl Into<Switch>) {
+        // Do a round way trip to be convert Into<Switch> -> bool
+        let enable: Switch = enable.into();
         let enable: bool = enable.into();
         match event {
             Event::AdcReady => self.reg.ier.modify(|_, w| w.adrdyie().bit(enable)),

src/gpio.rs

@@ -66,7 +66,7 @@ use crate::{
     hal::digital::v2::OutputPin,
     pac::{Interrupt, EXTI},
     rcc::AHB,
-    Toggle,
+    Switch,
 };
 
 use crate::hal::digital::v2::{toggleable, InputPin, StatefulOutputPin};
@@ -623,10 +623,10 @@ where
     ///
     /// Remeber to also configure the interrupt pin on
     /// the SysCfg site, with [`crate::syscfg::SysCfg::select_exti_interrupt_source()`]
-    pub fn configure_interrupt(&mut self, exti: &mut EXTI, enable: impl Into<Toggle>) {
+    pub fn configure_interrupt(&mut self, exti: &mut EXTI, enable: impl Into<Switch>) {
         const BITWIDTH: u8 = 1;
 
-        let enable: Toggle = enable.into();
+        let enable: Switch = enable.into();
         let enable: bool = enable.into();
 
         let index = self.index.index();
@@ -642,12 +642,12 @@ where
     /// Remeber to also configure the interrupt pin on
     /// the SysCfg site, with [`crate::syscfg::SysCfg::select_exti_interrupt_source()`]
     pub fn enable_interrupt(&mut self, exti: &mut EXTI) {
-        self.configure_interrupt(exti, Toggle::On)
+        self.configure_interrupt(exti, Switch::On)
     }
 
     /// Disable external interrupts from this pin
     pub fn disable_interrupt(&mut self, exti: &mut EXTI) {
-        self.configure_interrupt(exti, Toggle::Off)
+        self.configure_interrupt(exti, Switch::Off)
     }
 
     /// Clear the interrupt pending bit for this pin

src/lib.rs

@@ -274,24 +274,50 @@ cfg_if! {
 // TODO: Maybe move to some mod like "util"?
 #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[deprecated(since = "0.10.0", note = "Use Switch instead")]
+#[allow(deprecated)]
 pub enum Toggle {
     /// Toggle something on / enable a thing.
     On,
     /// Toggle something off / disable a thing.
     Off,
 }
 
-impl From<Toggle> for bool {
+/// Switch something on or off.
+///
+/// Convenience enum and wrapper around a bool, which more explicit about the intention to enable
+/// or disable something, in comparison to `true` or `false`.
+// TODO: Maybe move to some mod like "util"?
+#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Clone, Copy)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum Switch {
+    /// Switch something on / enable a thing.
+    On,
+    /// Switch something off / disable a thing.
+    Off,
+}
+
+#[allow(deprecated)]
+impl From<Toggle> for Switch {
     fn from(toggle: Toggle) -> Self {
-        matches!(toggle, Toggle::On)
+        match toggle {
+            Toggle::On => Switch::On,
+            Toggle::Off => Switch::Off,
+        }
+    }
+}
+
+impl From<Switch> for bool {
+    fn from(switch: Switch) -> Self {
+        matches!(switch, Switch::On)
     }
 }
 
-impl From<bool> for Toggle {
+impl From<bool> for Switch {
     fn from(b: bool) -> Self {
         match b {
-            true => Toggle::On,
-            false => Toggle::Off,
+            true => Switch::On,
+            false => Switch::Off,
         }
     }
 }

src/serial.rs

@@ -24,7 +24,7 @@ use crate::{
     },
     rcc::{self, Clocks},
     time::rate::*,
-    Toggle,
+    Switch,
 };
 
 #[allow(unused_imports)]
@@ -623,20 +623,20 @@ where
     /// Enable the interrupt for the specified [`Event`].
     #[inline]
     pub fn enable_interrupt(&mut self, event: Event) {
-        self.configure_interrupt(event, Toggle::On);
+        self.configure_interrupt(event, Switch::On);
     }
 
     /// Disable the interrupt for the specified [`Event`].
     #[inline]
     pub fn disable_interrupt(&mut self, event: Event) {
-        self.configure_interrupt(event, Toggle::Off);
+        self.configure_interrupt(event, Switch::Off);
     }
 
     /// Enable or disable the interrupt for the specified [`Event`].
     #[inline]
-    pub fn configure_interrupt(&mut self, event: Event, enable: impl Into<Toggle>) {
-        // Do a round way trip to be convert Into<Toggle> -> bool
-        let enable: Toggle = enable.into();
+    pub fn configure_interrupt(&mut self, event: Event, enable: impl Into<Switch>) {
+        // Do a round way trip to be convert Into<Switch> -> bool
+        let enable: Switch = enable.into();
         let enable: bool = enable.into();
         match event {
             Event::TransmitDataRegisterEmtpy => self.usart.cr1.modify(|_, w| w.txeie().bit(enable)),