Add traits for common methods on nodes and properties.

Author: qwandor

src/fdt/mod.rs

@@ -30,6 +30,7 @@ pub use self::node::FdtNode;
 pub use self::property::{Cells, FdtProperty};
 use crate::error::{FdtErrorKind, FdtParseError};
 use crate::memreserve::MemoryReservation;
+use crate::standard::Node;
 
 /// Version of the FDT specification supported by this library.
 const FDT_VERSION: u32 = 17;
@@ -487,7 +488,9 @@ impl<'a> Fdt<'a> {
     /// # Examples
     ///
     /// ```
-    /// # use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::standard::Node;
+    ///
     /// # let dtb = include_bytes!("../../tests/dtb/test.dtb");
     /// let fdt = Fdt::new(dtb).unwrap();
     /// let root = fdt.root();
@@ -528,15 +531,19 @@ impl<'a> Fdt<'a> {
     /// # Examples
     ///
     /// ```
-    /// # use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::standard::Node;
+    ///
     /// # let dtb = include_bytes!("../../tests/dtb/test_traversal.dtb");
     /// let fdt = Fdt::new(dtb).unwrap();
     /// let node = fdt.find_node("/a/b/c").unwrap();
     /// assert_eq!(node.name(), "c");
     /// ```
     ///
     /// ```
-    /// # use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::standard::Node;
+    ///
     /// # let dtb = include_bytes!("../../tests/dtb/test_children.dtb");
     /// let fdt = Fdt::new(dtb).unwrap();
     /// let node = fdt.find_node("/child2").unwrap();

src/fdt/node.rs

@@ -12,7 +12,7 @@ use core::fmt::{self, Display, Formatter};
 
 use super::{FDT_TAGSIZE, Fdt, FdtToken};
 use crate::fdt::property::{FdtPropIter, FdtProperty};
-use crate::standard::AddressSpaceProperties;
+use crate::standard::{AddressSpaceProperties, Node, Property};
 
 /// A node in a flattened device tree.
 #[derive(Debug, Clone, Copy)]
@@ -24,14 +24,8 @@ pub struct FdtNode<'a> {
     pub(crate) parent_address_space: AddressSpaceProperties,
 }
 
-impl<'a> FdtNode<'a> {
-    pub(crate) fn new(fdt: Fdt<'a>, offset: usize) -> Self {
-        Self {
-            fdt,
-            offset,
-            parent_address_space: AddressSpaceProperties::default(),
-        }
-    }
+impl<'a> Node<'a> for FdtNode<'a> {
+    type Property = FdtProperty<'a>;
 
     /// Returns the name of this node.
     ///
@@ -44,38 +38,22 @@ impl<'a> FdtNode<'a> {
     /// # Examples
     ///
     /// ```
-    /// # use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::standard::Node;
+    ///
     /// # let dtb = include_bytes!("../../tests/dtb/test_children.dtb");
     /// let fdt = Fdt::new(dtb).unwrap();
     /// let root = fdt.root();
     /// let child = root.child("child1").unwrap();
     /// assert_eq!(child.name(), "child1");
     /// ```
-    #[must_use]
-    pub fn name(&self) -> &'a str {
+    fn name(&self) -> &'a str {
         let name_offset = self.offset + FDT_TAGSIZE;
         self.fdt
             .string_at_offset(name_offset, None)
             .expect("Fdt should be valid")
     }
 
-    /// Returns the name of this node without the unit address, if any.
-    ///
-    /// # Panics
-    ///
-    /// Panics if the [`Fdt`] structure was constructed using
-    /// [`Fdt::new_unchecked`] or [`Fdt::from_raw_unchecked`] and the FDT is not
-    /// valid.
-    #[must_use]
-    pub fn name_without_address(&self) -> &'a str {
-        let name = self.name();
-        if let Some((name, _)) = name.split_once('@') {
-            name
-        } else {
-            name
-        }
-    }
-
     /// Returns a property by its name.
     ///
     /// # Performance
@@ -85,7 +63,9 @@ impl<'a> FdtNode<'a> {
     /// # Examples
     ///
     /// ```
-    /// # use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::standard::{Node, Property};
+    ///
     /// # let dtb = include_bytes!("../../tests/dtb/test_props.dtb");
     /// let fdt = Fdt::new(dtb).unwrap();
     /// let node = fdt.find_node("/test-props").unwrap();
@@ -98,8 +78,7 @@ impl<'a> FdtNode<'a> {
     /// Panics if the [`Fdt`] structure was constructed using
     /// [`Fdt::new_unchecked`] or [`Fdt::from_raw_unchecked`] and the FDT is not
     /// valid.
-    #[must_use]
-    pub fn property(&self, name: &str) -> Option<FdtProperty<'a>> {
+    fn property(&self, name: &str) -> Option<FdtProperty<'a>> {
         self.properties().find(|property| property.name() == name)
     }
 
@@ -108,7 +87,9 @@ impl<'a> FdtNode<'a> {
     /// # Examples
     ///
     /// ```
-    /// # use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::standard::{Node, Property};
+    ///
     /// # let dtb = include_bytes!("../../tests/dtb/test_props.dtb");
     /// let fdt = Fdt::new(dtb).unwrap();
     /// let node = fdt.find_node("/test-props").unwrap();
@@ -117,78 +98,21 @@ impl<'a> FdtNode<'a> {
     /// assert_eq!(props.next().unwrap().name(), "u64-prop");
     /// assert_eq!(props.next().unwrap().name(), "str-prop");
     /// ```
-    pub fn properties(&self) -> impl Iterator<Item = FdtProperty<'a>> + use<'a> {
+    fn properties(&self) -> impl Iterator<Item = FdtProperty<'a>> + use<'a> {
         FdtPropIter::Start {
             fdt: self.fdt,
             offset: self.offset,
         }
     }
 
-    /// Returns a child node by its name.
-    ///
-    /// If the given name contains a _unit-address_ (the part after the `@`
-    /// sign) then both the _node-name_ and _unit-address_ must match. If it
-    /// doesn't have a _unit-address_, then nodes with any _unit-address_ or
-    /// none will be allowed.
-    ///
-    /// For example, searching for `memory` as a child of `/` would match either
-    /// `/memory` or `/memory@4000`, while `memory@4000` would match only the
-    /// latter.
-    ///
-    /// # Performance
-    ///
-    /// This method's performance is linear in the number of children of this
-    /// node because it iterates through the children. If you need to call this
-    /// often, consider converting to a
-    /// [`DeviceTreeNode`](crate::model::DeviceTreeNode) first. Child lookup
-    /// on a [`DeviceTreeNode`](crate::model::DeviceTreeNode) is a
-    /// constant-time operation.
-    ///
-    /// # Panics
-    ///
-    /// Panics if the [`Fdt`] structure was constructed using
-    /// [`Fdt::new_unchecked`] or [`Fdt::from_raw_unchecked`] and the FDT is not
-    /// valid.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # use dtoolkit::fdt::Fdt;
-    /// # let dtb = include_bytes!("../../tests/dtb/test_children.dtb");
-    /// let fdt = Fdt::new(dtb).unwrap();
-    /// let root = fdt.root();
-    /// let child = root.child("child1").unwrap();
-    /// assert_eq!(child.name(), "child1");
-    /// ```
-    ///
-    /// ```
-    /// # use dtoolkit::fdt::Fdt;
-    /// # let dtb = include_bytes!("../../tests/dtb/test_children.dtb");
-    /// let fdt = Fdt::new(dtb).unwrap();
-    /// let root = fdt.root();
-    /// let child = root.child("child2").unwrap();
-    /// assert_eq!(child.name(), "child2@42");
-    /// let child = root.child("child2@42").unwrap();
-    /// assert_eq!(child.name(), "child2@42");
-    /// ```
-    #[must_use]
-    pub fn child(&self, name: &str) -> Option<FdtNode<'a>> {
-        let include_address = name.contains('@');
-        self.children().find(|&child| {
-            if include_address {
-                child.name() == name
-            } else {
-                child.name_without_address() == name
-            }
-        })
-    }
-
     /// Returns an iterator over the children of this node.
     ///
     /// # Examples
     ///
     /// ```
-    /// # use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::fdt::Fdt;
+    /// use dtoolkit::standard::Node;
+    ///
     /// # let dtb = include_bytes!("../../tests/dtb/test_children.dtb");
     /// let fdt = Fdt::new(dtb).unwrap();
     /// let root = fdt.root();
@@ -197,9 +121,19 @@ impl<'a> FdtNode<'a> {
     /// assert_eq!(children.next().unwrap().name(), "child2@42");
     /// assert!(children.next().is_none());
     /// ```
-    pub fn children(&self) -> impl Iterator<Item = FdtNode<'a>> + use<'a> {
+    fn children(&self) -> impl Iterator<Item = FdtNode<'a>> + use<'a> {
         FdtChildIter::Start { node: *self }
     }
+}
+
+impl<'a> FdtNode<'a> {
+    pub(crate) fn new(fdt: Fdt<'a>, offset: usize) -> Self {
+        Self {
+            fdt,
+            offset,
+            parent_address_space: AddressSpaceProperties::default(),
+        }
+    }
 
     pub(crate) fn fmt_recursive(&self, f: &mut Formatter, indent: usize) -> fmt::Result {
         let name = self.name();

src/fdt/property.rs

@@ -16,6 +16,7 @@ use zerocopy::{FromBytes, big_endian};
 
 use super::{FDT_TAGSIZE, Fdt, FdtToken};
 use crate::error::{PropertyError, StandardError};
+use crate::standard::Property;
 
 /// A property of a device tree node.
 #[derive(Debug, PartialEq)]
@@ -25,108 +26,35 @@ pub struct FdtProperty<'a> {
     value_offset: usize,
 }
 
-impl<'a> FdtProperty<'a> {
-    /// Returns the name of this property.
-    #[must_use]
-    pub fn name(&self) -> &'a str {
+impl<'a> Property<'a> for FdtProperty<'a> {
+    fn name(&self) -> &'a str {
         self.name
     }
 
-    /// Returns the value of this property.
-    #[must_use]
-    pub fn value(&self) -> &'a [u8] {
+    fn value(&self) -> &'a [u8] {
         self.value
     }
 
-    /// Returns the value of this property as a `u32`.
-    ///
-    /// # Errors
-    ///
-    /// Returns an [`PropertyError::InvalidLength`] if the property's value is
-    /// not 4 bytes long.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # use dtoolkit::fdt::Fdt;
-    /// # let dtb = include_bytes!("../../tests/dtb/test_props.dtb");
-    /// let fdt = Fdt::new(dtb).unwrap();
-    /// let node = fdt.find_node("/test-props").unwrap();
-    /// let prop = node.property("u32-prop").unwrap();
-    /// assert_eq!(prop.as_u32().unwrap(), 0x12345678);
-    /// ```
-    pub fn as_u32(&self) -> Result<u32, PropertyError> {
+    fn as_u32(&self) -> Result<u32, PropertyError> {
         big_endian::U32::ref_from_bytes(self.value)
             .map(|val| val.get())
             .map_err(|_e| PropertyError::InvalidLength)
     }
 
-    /// Returns the value of this property as a `u64`.
-    ///
-    /// # Errors
-    ///
-    /// Returns an [`PropertyError::InvalidLength`] if the property's value is
-    /// not 8 bytes long.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # use dtoolkit::fdt::Fdt;
-    /// # let dtb = include_bytes!("../../tests/dtb/test_props.dtb");
-    /// let fdt = Fdt::new(dtb).unwrap();
-    /// let node = fdt.find_node("/test-props").unwrap();
-    /// let prop = node.property("u64-prop").unwrap();
-    /// assert_eq!(prop.as_u64().unwrap(), 0x1122334455667788);
-    /// ```
-    pub fn as_u64(&self) -> Result<u64, PropertyError> {
+    fn as_u64(&self) -> Result<u64, PropertyError> {
         big_endian::U64::ref_from_bytes(self.value)
             .map(|val| val.get())
             .map_err(|_e| PropertyError::InvalidLength)
     }
 
-    /// Returns the value of this property as a string.
-    ///
-    /// # Errors
-    ///
-    /// Returns an [`PropertyError::InvalidString`] if the property's value is
-    /// not a null-terminated string or contains invalid UTF-8.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # use dtoolkit::fdt::Fdt;
-    /// # let dtb = include_bytes!("../../tests/dtb/test_props.dtb");
-    /// let fdt = Fdt::new(dtb).unwrap();
-    /// let node = fdt.find_node("/test-props").unwrap();
-    /// let prop = node.property("str-prop").unwrap();
-    /// assert_eq!(prop.as_str().unwrap(), "hello world");
-    /// ```
-    pub fn as_str(&self) -> Result<&'a str, PropertyError> {
+    fn as_str(&self) -> Result<&'a str, PropertyError> {
         let cstr =
             CStr::from_bytes_with_nul(self.value).map_err(|_| PropertyError::InvalidString)?;
         cstr.to_str().map_err(|_| PropertyError::InvalidString)
     }
+}
 
-    /// Returns an iterator over the strings in this property.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # use dtoolkit::fdt::Fdt;
-    /// # let dtb = include_bytes!("../../tests/dtb/test_props.dtb");
-    /// let fdt = Fdt::new(dtb).unwrap();
-    /// let node = fdt.find_node("/test-props").unwrap();
-    /// let prop = node.property("str-list-prop").unwrap();
-    /// let mut str_list = prop.as_str_list();
-    /// assert_eq!(str_list.next(), Some("first"));
-    /// assert_eq!(str_list.next(), Some("second"));
-    /// assert_eq!(str_list.next(), Some("third"));
-    /// assert_eq!(str_list.next(), None);
-    /// ```
-    pub fn as_str_list(&self) -> impl Iterator<Item = &'a str> + use<'a> {
-        FdtStringListIterator { value: self.value }
-    }
-
+impl<'a> FdtProperty<'a> {
     pub(crate) fn as_prop_encoded_array<const N: usize>(
         &self,
         fields_cells: [usize; N],
@@ -269,24 +197,6 @@ impl<'a> FdtPropIter<'a> {
     }
 }
 
-struct FdtStringListIterator<'a> {
-    value: &'a [u8],
-}
-
-impl<'a> Iterator for FdtStringListIterator<'a> {
-    type Item = &'a str;
-
-    fn next(&mut self) -> Option<Self::Item> {
-        if self.value.is_empty() {
-            return None;
-        }
-        let cstr = CStr::from_bytes_until_nul(self.value).ok()?;
-        let s = cstr.to_str().ok()?;
-        self.value = &self.value[s.len() + 1..];
-        Some(s)
-    }
-}
-
 /// An integer value split into several big-endian u32 parts.
 ///
 /// This is generally used in prop-encoded-array properties.