Contributes to #9943: Add docstrings and doctests, fix is_safe logic, and improve code formatting

[akiels]

Contributes to #9943

This PR improves the count-islands-in-matrix implementation by:

1. Adding docstrings and doctests for all methods (Matrix, is_safe, diffs, and count_islands)

2. Applying code formatting for consistency and pre-commit compliance (e.g., removing trailing whitespace, fixing parentheses).

3. Fixing a logic bug in is_safe:

• Previously, is_safe() could return int values 1 or 0 instead of expected boolean values (True or False).

• This was corrected by adding a condition to self.graph[i][j], which ensures that is_safe() doesn't return the value of a cell (int values 1 or 0) but instead returns True if the cell has value 1 and False otherwise (value 0).

Since this is a small logic fix, I include it in this PR along with the docs, tests, and formatting changes.

All changes pass local testing with doctest and pre-commit hooks.

These changes together improve the clarity, functionality, and test coverage of the implementation.

Thank you for reviewing!

[cclauss]

@priya-sundaram-dev In the matrix/count_islands_in_matrix.py file on the master branch, is there a logic error in is_safe()?

[priya-sundaram-dev]

@cclauss Ran the master version through python -m doctest first — all 18 doctests pass, so there's no crashing bug. But yes, there's a real defect in is_safe(), and it's a two-parter:

1. It violates its own -> bool contract. The final operand is bare:

and self.graph[i][j]

Because and returns the last-evaluated operand, is_safe hands back the cell value (an int), not a bool. That's why the current doctests have to assert 1/0 instead of True/False, and why m.is_safe(0, 0, visited) is True is actually False. The == 1 fix in #12691 is the right call (or bool(self.graph[i][j])).

2. There's a latent consistency bug hiding behind that. count_islands() seeds islands only where self.graph[i][j] == 1, but is_safe()/diffs() expand into any truthy cell (self.graph[i][j]). For a strict 0/1 matrix these agree, but for any other value they diverge — e.g. a cell holding 2:

is_safe(0,0) -> 2   (treated as land)
count_islands() -> 0 (never seeded, since 2 != 1)

So == 1 isn't just cosmetic — it aligns is_safe with count_islands' seeding rule and closes that gap.

Bounds are fine, for what it's worth: the 0 <= i < self.ROW and 0 <= j < self.COL checks short-circuit before the visited[i][j]/graph[i][j] indexing, so no IndexError on the neighbor sweep.

tl;dr: not an algorithm error, but a genuine return-type + seeding-consistency bug. and self.graph[i][j] == 1 fixes both.

[cclauss]

@akiels and @priya-sundaram-dev can you please both EACH (separately) create a pull request that ensures that is_safe() -> bool actually returns a bool and count_islands() has test cases that prove where our algorithms have been giving improper results. We can compare those two PRs to reach consensus.

[priya-sundaram-dev]

Done — opened #15363 with just the two-line `is_safe` fix (and self.graph[i][j] == 1) plus doctests. The key count_islands proof is [[1, 2, 1]]: two 1-islands bridged by a non-island 2. The old truthy is_safe absorbed the 2 and merged them → returned 1; corrected it returns 2. Also added out-of-bounds, diagonal-only, and lone-2 cases. Happy to compare against @akiels' PR to reach consensus. cc @cclauss