Merge #178

178: register, cluster iterators r=Emilgardis a=burrbull



Co-authored-by: Andrey Zgarbul <[email protected]>

Author: bors[bot]

svd-rs/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+- Rename `reg_iter` to `all_registers`, add `registers`, `clusters` methods that create iterators
+
 ## [v0.12.0] - 2021-11-11
 
 - Bump dependencies

svd-rs/src/clusterinfo.rs

@@ -1,5 +1,8 @@
 use super::{
-    register::{RegIter, RegIterMut},
+    registercluster::{
+        AllRegistersIter, AllRegistersIterMut, ClusterIter, ClusterIterMut, RegisterIter,
+        RegisterIterMut,
+    },
     BuildError, Cluster, DimElement, EmptyToNone, RegisterCluster, RegisterProperties, SvdError,
     ValidateLevel,
 };
@@ -226,21 +229,61 @@ impl ClusterInfo {
         Ok(())
     }
 
-    /// returns a iterator over all registers the cluster contains
-    pub fn reg_iter(&self) -> RegIter {
+    /// Returns iterator over all descendant registers
+    #[deprecated(since = "0.12.1", note = "Please use `all_registers` instead")]
+    pub fn reg_iter(&self) -> AllRegistersIter {
+        self.all_registers()
+    }
+
+    /// Returns iterator over all descendant registers
+    pub fn all_registers(&self) -> AllRegistersIter {
         let mut rem: Vec<&RegisterCluster> = Vec::with_capacity(self.children.len());
         for r in self.children.iter().rev() {
             rem.push(r);
         }
-        RegIter { rem }
+        AllRegistersIter { rem }
+    }
+
+    /// Returns mutable iterator over all descendant registers
+    #[deprecated(since = "0.12.1", note = "Please use `all_registers_mut` instead")]
+    pub fn reg_iter_mut(&mut self) -> AllRegistersIterMut {
+        self.all_registers_mut()
     }
 
-    /// returns a mutable iterator over all registers cluster contains
-    pub fn reg_iter_mut(&mut self) -> RegIterMut {
+    /// Returns mutable iterator over all descendant registers
+    pub fn all_registers_mut(&mut self) -> AllRegistersIterMut {
         let mut rem: Vec<&mut RegisterCluster> = Vec::with_capacity(self.children.len());
         for r in self.children.iter_mut().rev() {
             rem.push(r);
         }
-        RegIterMut { rem }
+        AllRegistersIterMut { rem }
+    }
+
+    /// Returns iterator over child registers
+    pub fn registers(&self) -> RegisterIter {
+        RegisterIter {
+            all: self.children.iter(),
+        }
+    }
+
+    /// Returns mutable iterator over child registers
+    pub fn registers_mut(&mut self) -> RegisterIterMut {
+        RegisterIterMut {
+            all: self.children.iter_mut(),
+        }
+    }
+
+    /// Returns iterator over child clusters
+    pub fn clusters(&self) -> ClusterIter {
+        ClusterIter {
+            all: self.children.iter(),
+        }
+    }
+
+    /// Returns mutable iterator over child clusters
+    pub fn clusters_mut(&mut self) -> ClusterIterMut {
+        ClusterIterMut {
+            all: self.children.iter_mut(),
+        }
     }
 }

svd-rs/src/peripheralinfo.rs

@@ -1,5 +1,8 @@
 use super::{
-    register::{RegIter, RegIterMut},
+    registercluster::{
+        AllRegistersIter, AllRegistersIterMut, ClusterIter, ClusterIterMut, OptIter, RegisterIter,
+        RegisterIterMut,
+    },
     AddressBlock, BuildError, DimElement, EmptyToNone, Interrupt, Peripheral, RegisterCluster,
     RegisterProperties, SvdError, ValidateLevel,
 };
@@ -357,29 +360,73 @@ impl PeripheralInfo {
         Ok(())
     }
 
-    /// returns iterator over all registers peripheral contains
-    pub fn reg_iter(&self) -> RegIter {
+    /// Returns iterator over child registers
+    pub fn registers(&self) -> OptIter<RegisterIter> {
+        OptIter::new(
+            self.registers
+                .as_ref()
+                .map(|regs| RegisterIter { all: regs.iter() }),
+        )
+    }
+
+    /// Returns mutable iterator over child registers
+    pub fn registers_mut(&mut self) -> OptIter<RegisterIterMut> {
+        OptIter::new(self.registers.as_mut().map(|regs| RegisterIterMut {
+            all: regs.iter_mut(),
+        }))
+    }
+
+    /// Returns iterator over child clusters
+    pub fn clusters(&self) -> OptIter<ClusterIter> {
+        OptIter::new(
+            self.registers
+                .as_ref()
+                .map(|regs| ClusterIter { all: regs.iter() }),
+        )
+    }
+
+    /// Returns mutable iterator over child clusters
+    pub fn clusters_mut(&mut self) -> OptIter<ClusterIterMut> {
+        OptIter::new(self.registers.as_mut().map(|regs| ClusterIterMut {
+            all: regs.iter_mut(),
+        }))
+    }
+
+    /// Returns iterator over all descendant registers
+    #[deprecated(since = "0.12.1", note = "Please use `all_registers` instead")]
+    pub fn reg_iter(&self) -> AllRegistersIter {
+        self.all_registers()
+    }
+
+    /// Returns iterator over all descendant registers
+    pub fn all_registers(&self) -> AllRegistersIter {
         if let Some(regs) = &self.registers {
             let mut rem: Vec<&RegisterCluster> = Vec::with_capacity(regs.len());
             for r in regs.iter().rev() {
                 rem.push(r);
             }
-            RegIter { rem }
+            AllRegistersIter { rem }
         } else {
-            RegIter { rem: Vec::new() }
+            AllRegistersIter { rem: Vec::new() }
         }
     }
 
-    /// returns mutable iterator over all registers peripheral contains
-    pub fn reg_iter_mut(&mut self) -> RegIterMut {
+    /// Returns mutable iterator over all descendant registers
+    #[deprecated(since = "0.12.1", note = "Please use `all_registers_mut` instead")]
+    pub fn reg_iter_mut(&mut self) -> AllRegistersIterMut {
+        self.all_registers_mut()
+    }
+
+    /// Returns mutable iterator over all descendant registers
+    pub fn all_registers_mut(&mut self) -> AllRegistersIterMut {
         if let Some(regs) = &mut self.registers {
             let mut rem: Vec<&mut RegisterCluster> = Vec::with_capacity(regs.len());
             for r in regs.iter_mut().rev() {
                 rem.push(r);
             }
-            RegIterMut { rem }
+            AllRegistersIterMut { rem }
         } else {
-            RegIterMut { rem: Vec::new() }
+            AllRegistersIterMut { rem: Vec::new() }
         }
     }
 }

svd-rs/src/register.rs

@@ -1,6 +1,8 @@
 use core::ops::{Deref, DerefMut};
 
-use super::{DimElement, RegisterCluster, RegisterInfo};
+#[doc(hidden)]
+pub use super::registercluster::{AllRegistersIter as RegIter, AllRegistersIterMut as RegIterMut};
+use super::{DimElement, RegisterInfo};
 
 /// A single register or array of registers. A register is a named, programmable resource that belongs to a [peripheral](crate::Peripheral).
 #[derive(Clone, Debug, PartialEq)]
@@ -42,54 +44,6 @@ impl Register {
     }
 }
 
-/// Register iterator
-pub struct RegIter<'a> {
-    pub(crate) rem: Vec<&'a RegisterCluster>,
-}
-
-impl<'a> std::iter::Iterator for RegIter<'a> {
-    type Item = &'a Register;
-    fn next(&mut self) -> Option<Self::Item> {
-        while let Some(b) = self.rem.pop() {
-            match b {
-                RegisterCluster::Register(reg) => {
-                    return Some(reg);
-                }
-                RegisterCluster::Cluster(cluster) => {
-                    for c in cluster.children.iter().rev() {
-                        self.rem.push(c);
-                    }
-                }
-            }
-        }
-        None
-    }
-}
-
-/// Mutable register iterator
-pub struct RegIterMut<'a> {
-    pub(crate) rem: Vec<&'a mut RegisterCluster>,
-}
-
-impl<'a> std::iter::Iterator for RegIterMut<'a> {
-    type Item = &'a mut Register;
-    fn next(&mut self) -> Option<Self::Item> {
-        while let Some(b) = self.rem.pop() {
-            match b {
-                RegisterCluster::Register(reg) => {
-                    return Some(reg);
-                }
-                RegisterCluster::Cluster(cluster) => {
-                    for c in cluster.children.iter_mut().rev() {
-                        self.rem.push(c);
-                    }
-                }
-            }
-        }
-        None
-    }
-}
-
 #[cfg(feature = "serde")]
 mod ser_de {
     use super::*;

svd-rs/src/registercluster.rs

@@ -25,3 +25,140 @@ impl From<Cluster> for RegisterCluster {
         RegisterCluster::Cluster(cluser)
     }
 }
+
+/// Register iterator
+pub struct RegisterIter<'a> {
+    pub(crate) all: std::slice::Iter<'a, RegisterCluster>,
+}
+
+impl<'a> std::iter::Iterator for RegisterIter<'a> {
+    type Item = &'a Register;
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.all.next() {
+            None => None,
+            Some(RegisterCluster::Register(reg)) => Some(reg),
+            _ => self.next(),
+        }
+    }
+}
+
+/// Mutable register iterator
+pub struct RegisterIterMut<'a> {
+    pub(crate) all: std::slice::IterMut<'a, RegisterCluster>,
+}
+
+impl<'a> std::iter::Iterator for RegisterIterMut<'a> {
+    type Item = &'a mut Register;
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.all.next() {
+            None => None,
+            Some(RegisterCluster::Register(reg)) => Some(reg),
+            _ => self.next(),
+        }
+    }
+}
+
+/// Cluster iterator
+pub struct ClusterIter<'a> {
+    pub(crate) all: std::slice::Iter<'a, RegisterCluster>,
+}
+
+impl<'a> std::iter::Iterator for ClusterIter<'a> {
+    type Item = &'a Cluster;
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.all.next() {
+            None => None,
+            Some(RegisterCluster::Cluster(c)) => Some(c),
+            _ => self.next(),
+        }
+    }
+}
+
+/// Mutable cluster iterator
+pub struct ClusterIterMut<'a> {
+    pub(crate) all: std::slice::IterMut<'a, RegisterCluster>,
+}
+
+impl<'a> std::iter::Iterator for ClusterIterMut<'a> {
+    type Item = &'a mut Cluster;
+    fn next(&mut self) -> Option<Self::Item> {
+        match self.all.next() {
+            None => None,
+            Some(RegisterCluster::Cluster(c)) => Some(c),
+            _ => self.next(),
+        }
+    }
+}
+
+/// Iterator over all registers
+pub struct AllRegistersIter<'a> {
+    pub(crate) rem: Vec<&'a RegisterCluster>,
+}
+
+impl<'a> std::iter::Iterator for AllRegistersIter<'a> {
+    type Item = &'a Register;
+    fn next(&mut self) -> Option<Self::Item> {
+        while let Some(b) = self.rem.pop() {
+            match b {
+                RegisterCluster::Register(reg) => {
+                    return Some(reg);
+                }
+                RegisterCluster::Cluster(cluster) => {
+                    for c in cluster.children.iter().rev() {
+                        self.rem.push(c);
+                    }
+                }
+            }
+        }
+        None
+    }
+}
+
+/// Mutable iterator over all registers
+pub struct AllRegistersIterMut<'a> {
+    pub(crate) rem: Vec<&'a mut RegisterCluster>,
+}
+
+impl<'a> std::iter::Iterator for AllRegistersIterMut<'a> {
+    type Item = &'a mut Register;
+    fn next(&mut self) -> Option<Self::Item> {
+        while let Some(b) = self.rem.pop() {
+            match b {
+                RegisterCluster::Register(reg) => {
+                    return Some(reg);
+                }
+                RegisterCluster::Cluster(cluster) => {
+                    for c in cluster.children.iter_mut().rev() {
+                        self.rem.push(c);
+                    }
+                }
+            }
+        }
+        None
+    }
+}
+
+/// Iterates over optional iterator
+pub struct OptIter<I>(Option<I>)
+where
+    I: Iterator;
+
+impl<I> OptIter<I>
+where
+    I: Iterator,
+{
+    /// Create new optional iterator
+    pub fn new(o: Option<I>) -> Self {
+        Self(o)
+    }
+}
+
+impl<'a, I> Iterator for OptIter<I>
+where
+    I: Iterator,
+{
+    type Item = I::Item;
+    fn next(&mut self) -> Option<Self::Item> {
+        self.0.as_mut().and_then(I::next)
+    }
+}