Merge #324

324: dfs reach r=samueltardieu a=samueltardieu

- Add dfs_reach()
- Deprecate Matrix::reachable() for bfs_reachable() and dfs_reachable()


Co-authored-by: Samuel Tardieu <[email protected]>

Author: bors[bot]

src/directed/dfs.rs

@@ -1,6 +1,9 @@
 //! Compute a path using the [depth-first search
 //! algorithm](https://en.wikipedia.org/wiki/Depth-first_search).
 
+use std::collections::HashSet;
+use std::hash::Hash;
+
 /// Compute a path using the [depth-first search
 /// algorithm](https://en.wikipedia.org/wiki/Depth-first_search).
 /// The path starts from `start` up to a node for which `success` returns `true` is computed and
@@ -77,3 +80,83 @@ where
         false
     }
 }
+
+/// Visit all nodes that are reachable from a start node. The node will be visited
+/// in DFS order, starting from the `start` node and following the order returned
+/// by the `successors` function.
+///
+/// # Examples
+///
+/// The iterator stops when there are no new nodes to visit:
+///
+/// ```
+/// use pathfinding::prelude::dfs_reach;
+///
+/// let all_nodes = dfs_reach(3, |_| (1..=5)).collect::<Vec<_>>();
+/// assert_eq!(all_nodes, vec![3, 1, 2, 4, 5]);
+/// ```
+///
+/// The iterator can be used as a generator. Here are for examples
+/// the multiples of 2 and 3 smaller than 15 (although not in
+/// natural order but in the order they are discovered by the DFS
+/// algorithm):
+///
+/// ```
+/// use pathfinding::prelude::dfs_reach;
+///
+/// let mut it = dfs_reach(1, |&n| vec![n*2, n*3].into_iter().filter(|&x| x < 15)).skip(1);
+/// assert_eq!(it.next(), Some(2));  // 1*2
+/// assert_eq!(it.next(), Some(4));  // (1*2)*2
+/// assert_eq!(it.next(), Some(8));  // ((1*2)*2)*2
+/// assert_eq!(it.next(), Some(12)); // ((1*2)*2)*3
+/// assert_eq!(it.next(), Some(6));  // (1*2)*3
+/// assert_eq!(it.next(), Some(3));  // 1*3
+/// // (1*3)*2 == 6 which has been seen already
+/// assert_eq!(it.next(), Some(9));  // (1*3)*3
+/// ```
+pub fn dfs_reach<N, FN, IN>(start: N, successors: FN) -> DfsReachable<N, FN>
+where
+    N: Eq + Hash + Clone,
+    FN: FnMut(&N) -> IN,
+    IN: IntoIterator<Item = N>,
+{
+    let (to_see, mut seen) = (vec![start.clone()], HashSet::new());
+    seen.insert(start);
+    DfsReachable {
+        to_see,
+        seen,
+        successors,
+    }
+}
+
+/// Struct returned by [`dfs_reach`](crate::directed::dfs::dfs_reach).
+pub struct DfsReachable<N, FN> {
+    to_see: Vec<N>,
+    seen: HashSet<N>,
+    successors: FN,
+}
+
+impl<N, FN, IN> Iterator for DfsReachable<N, FN>
+where
+    N: Eq + Hash + Clone,
+    FN: FnMut(&N) -> IN,
+    IN: IntoIterator<Item = N>,
+{
+    type Item = N;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if let Some(n) = self.to_see.pop() {
+            let mut to_insert = Vec::new();
+            for s in (self.successors)(&n) {
+                if !self.seen.contains(&s) {
+                    to_insert.push(s.clone());
+                    self.seen.insert(s);
+                }
+            }
+            self.to_see.extend(to_insert.into_iter().rev());
+            Some(n)
+        } else {
+            None
+        }
+    }
+}

src/matrix.rs

@@ -1,6 +1,7 @@
 //! Matrix of an arbitrary type and utilities to rotate, transpose, etc.
 
 use crate::directed::bfs::bfs_reach;
+use crate::directed::dfs::dfs_reach;
 use crate::utils::uint_sqrt;
 use itertools::iproduct;
 use itertools::Itertools;
@@ -534,7 +535,37 @@ impl<C> Matrix<C> {
     /// to implement a flood-filling algorithm. Since the indices are collected
     /// into a vector, they can later be used without keeping a reference on the
     /// matrix itself, e.g., to modify the matrix.
+    ///
+    /// This method calls the [`bfs_reachable()`](`Self::bfs_reachable`) method to
+    /// do its work.
+    #[deprecated(
+        since = "3.0.7",
+        note = "Use `bfs_reachable()` or `dfs_reachable()` methods instead"
+    )]
     pub fn reachable<P>(
+        &self,
+        start: (usize, usize),
+        diagonals: bool,
+        predicate: P,
+    ) -> BTreeSet<(usize, usize)>
+    where
+        P: FnMut((usize, usize)) -> bool + Copy,
+    {
+        self.bfs_reachable(start, diagonals, predicate)
+    }
+
+    /// Return a set of the indices reachable from a candidate starting point
+    /// and for which the given predicate is valid. This can be used for example
+    /// to implement a flood-filling algorithm. Since the indices are collected
+    /// into a vector, they can later be used without keeping a reference on the
+    /// matrix itself, e.g., to modify the matrix.
+    ///
+    /// The search is done using a breadth first search (BFS) algorithm.
+    ///
+    /// # See also
+    ///
+    /// The [`dfs_reachable()`](`Self::dfs_reachable`) performs a DFS search instead.
+    pub fn bfs_reachable<P>(
         &self,
         start: (usize, usize),
         diagonals: bool,
@@ -548,6 +579,32 @@ impl<C> Matrix<C> {
         })
         .collect()
     }
+
+    /// Return a set of the indices reachable from a candidate starting point
+    /// and for which the given predicate is valid. This can be used for example
+    /// to implement a flood-filling algorithm. Since the indices are collected
+    /// into a vector, they can later be used without keeping a reference on the
+    /// matrix itself, e.g., to modify the matrix.
+    ///
+    /// The search is done using a depth first search (DFS) algorithm.
+    ///
+    /// # See also
+    ///
+    /// The [`bfs_reachable()`](`Self::bfs_reachable`) performs a BFS search instead.
+    pub fn dfs_reachable<P>(
+        &self,
+        start: (usize, usize),
+        diagonals: bool,
+        mut predicate: P,
+    ) -> BTreeSet<(usize, usize)>
+    where
+        P: FnMut((usize, usize)) -> bool + Copy,
+    {
+        dfs_reach(start, |&n| {
+            self.neighbours(n, diagonals).filter(move |&n| predicate(n))
+        })
+        .collect()
+    }
 }
 
 impl<C> Index<(usize, usize)> for Matrix<C> {

tests/matrix.rs

@@ -380,6 +380,7 @@ fn empty_neighbours() {
 }
 
 #[test]
+#[allow(deprecated)]
 fn reachable() {
     let m = matrix![[0, 1, 2], [3, 4, 5], [6, 7, 8]];
 
@@ -396,6 +397,40 @@ fn reachable() {
     );
 }
 
+#[test]
+fn bfs_reachable() {
+    let m = matrix![[0, 1, 2], [3, 4, 5], [6, 7, 8]];
+
+    let indices = m.bfs_reachable((1, 0), false, |n| m[n] % 4 != 0);
+    assert_eq!(
+        indices.into_iter().collect::<Vec<_>>(),
+        vec![(1, 0), (2, 0), (2, 1)]
+    );
+
+    let indices = m.bfs_reachable((1, 0), true, |n| m[n] % 4 != 0);
+    assert_eq!(
+        indices.into_iter().collect::<Vec<_>>(),
+        vec![(0, 1), (0, 2), (1, 0), (1, 2), (2, 0), (2, 1)]
+    );
+}
+
+#[test]
+fn dfs_reachable() {
+    let m = matrix![[0, 1, 2], [3, 4, 5], [6, 7, 8]];
+
+    let indices = m.dfs_reachable((1, 0), false, |n| m[n] % 4 != 0);
+    assert_eq!(
+        indices.into_iter().collect::<Vec<_>>(),
+        vec![(1, 0), (2, 0), (2, 1)]
+    );
+
+    let indices = m.dfs_reachable((1, 0), true, |n| m[n] % 4 != 0);
+    assert_eq!(
+        indices.into_iter().collect::<Vec<_>>(),
+        vec![(0, 1), (0, 2), (1, 0), (1, 2), (2, 0), (2, 1)]
+    );
+}
+
 #[test]
 fn bounds_test() {
     let mut m = matrix![[0, 1, 2], [3, 4, 5]];