Add trait to abstract over selectable collections of elements

src/element_ref/mod.rs

@@ -1,5 +1,6 @@
 //! Element references.
 
+use std::iter::FusedIterator;
 use std::ops::Deref;
 
 use ego_tree::iter::{Edge, Traverse};
@@ -145,6 +146,8 @@ impl<'a, 'b> Iterator for Select<'a, 'b> {
     }
 }
 
+impl FusedIterator for Select<'_, '_> {}
+
 /// Iterator over descendent text nodes.
 #[derive(Debug, Clone)]
 pub struct Text<'a> {

src/html/mod.rs

@@ -2,6 +2,7 @@
 
 #[cfg(feature = "errors")]
 use std::borrow::Cow;
+use std::iter::FusedIterator;
 
 use ego_tree::iter::Nodes;
 use ego_tree::Tree;
@@ -161,6 +162,8 @@ impl<'a, 'b> DoubleEndedIterator for Select<'a, 'b> {
     }
 }
 
+impl FusedIterator for Select<'_, '_> {}
+
 mod serializable;
 mod tree_sink;
 

src/lib.rs

@@ -149,6 +149,7 @@ pub mod element_ref;
 pub mod error;
 pub mod html;
 pub mod node;
+pub mod selectable;
 pub mod selector;
 
 #[cfg(feature = "atomic")]

src/selectable.rs

@@ -0,0 +1,70 @@
+//! Provides the [`Selectable`] to abstract over collections of elements
+
+use crate::{
+    element_ref::{self, ElementRef},
+    html::{self, Html},
+    selector::Selector,
+};
+
+/// Trait to abstract over collections of elements to which a [CSS selector][Selector] can be applied
+///
+/// The mainly enables writing helper functions which are generic over [`Html`] and [`ElementRef`], e.g.
+///
+/// ```
+/// use scraper::{selectable::Selectable, selector::Selector};
+///
+/// fn text_of_first_match<'a, S>(selectable: S, selector: &Selector) -> Option<String>
+/// where
+///     S: Selectable<'a>,
+/// {
+///     selectable.select(selector).next().map(|element| element.text().collect())
+/// }
+/// ```
+pub trait Selectable<'a> {
+    /// Iterator over [element references][ElementRef] matching a [CSS selector[Selector]
+    type Select<'b>: Iterator<Item = ElementRef<'a>>;
+
+    /// Applies the given `selector` to the collection of elements represented by `self`
+    fn select(self, selector: &Selector) -> Self::Select<'_>;
+}
+
+impl<'a> Selectable<'a> for &'a Html {
+    type Select<'b> = html::Select<'a, 'b>;
+
+    fn select(self, selector: &Selector) -> Self::Select<'_> {
+        Html::select(self, selector)
+    }
+}
+
+impl<'a> Selectable<'a> for ElementRef<'a> {
+    type Select<'b> = element_ref::Select<'a, 'b>;
+
+    fn select(self, selector: &Selector) -> Self::Select<'_> {
+        ElementRef::select(&self, selector)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn select_one<'a, S>(selectable: S, selector: &Selector) -> Option<ElementRef<'a>>
+    where
+        S: Selectable<'a>,
+    {
+        selectable.select(selector).next()
+    }
+
+    #[test]
+    fn html_and_element_ref_are_selectable() {
+        let fragment = Html::parse_fragment(
+            r#"<select class="foo"><option value="bar">foobar</option></select>"#,
+        );
+
+        let selector = Selector::parse("select.foo").unwrap();
+        let element = select_one(&fragment, &selector).unwrap();
+
+        let selector = Selector::parse("select.foo option[value='bar']").unwrap();
+        let _element = select_one(element, &selector).unwrap();
+    }
+}