fix(matrix): make is_safe() return bool and prove count_islands' improper results

matrix/count_islands_in_matrix.py

@@ -31,21 +31,36 @@ def is_safe(self, i: int, j: int, visited: list[list[bool]]) -> bool:
             j (int): column index
             visited (list[list[bool]]): 2D list tracking the visited cells
         Returns:
-            bool: True if the cell is valid and part of the island
-            (1 for True and ) for False)
+            bool: True if the cell is in bounds, not yet visited and part of
+            an island (its value is ``1``); False otherwise.
         >>> visited = [[False, False], [False, False]]
         >>> graph = [[1, 0], [0, 1]]
         >>> m = Matrix(2, 2, graph)
         >>> m.is_safe(0, 0, visited)
-        1
+        True
         >>> m.is_safe(0, 1, visited)
-        0
+        False
+
+        A cell that is out of bounds is never safe:
+
+        >>> m.is_safe(-1, 0, visited)
+        False
+        >>> m.is_safe(0, 2, visited)
+        False
+
+        Only cells whose value is exactly ``1`` are part of an island, so any
+        other value (e.g. ``2``) is treated as water, matching the seeding rule
+        used by ``count_islands``:
+
+        >>> m2 = Matrix(1, 1, [[2]])
+        >>> m2.is_safe(0, 0, [[False]])
+        False
         """
         return (
             0 <= i < self.ROW
             and 0 <= j < self.COL
             and not visited[i][j]
-            and self.graph[i][j]
+            and self.graph[i][j] == 1
         )
 
     def diffs(self, i: int, j: int, visited: list[list[bool]]) -> None:
@@ -82,6 +97,32 @@ def count_islands(self) -> int:  # And finally, count all islands.
         >>> mat2 = Matrix(2, 2, [[0, 0], [0, 0]])
         >>> mat2.count_islands()
         0
+
+        Two 1s that only touch on a diagonal still form a single island:
+
+        >>> Matrix(2, 2, [[1, 0], [0, 1]]).count_islands()
+        1
+
+        Two islands separated by a column of water:
+
+        >>> Matrix(3, 3, [[1, 0, 1], [1, 0, 1], [0, 0, 1]]).count_islands()
+        2
+
+        ``count_islands`` seeds a new island only on cells equal to ``1``.
+        Before ``is_safe`` was aligned to the same rule it expanded into any
+        truthy cell, so a matrix containing values other than ``0``/``1``
+        reported the wrong count.  Here two ``1``s are bridged by a ``2``:
+        because a ``2`` is not part of an island they must be counted as two
+        separate islands.  The old truthy check absorbed the ``2`` and
+        merged them into one, returning ``1`` instead of ``2``:
+
+        >>> Matrix(1, 3, [[1, 2, 1]]).count_islands()
+        2
+
+        A lone ``2`` is likewise not an island:
+
+        >>> Matrix(1, 1, [[2]]).count_islands()
+        0
         """
         visited = [[False for j in range(self.COL)] for i in range(self.ROW)]
         count = 0