Deprecate Matrix::reachable() for bfs_reachable() and dfs_reachable()

Author: samueltardieu

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]];