Merge branch 'master' into odd-even-sort-comparable

Author: aayushgupta7725

CONTRIBUTING.md

@@ -196,7 +196,7 @@ Comments which are not on the same line as code should appear ___before___ the c
       return a + b
   ```
 
-  [Install ty](https://docs.astral.sh/ty/installation/) and then pslease use the command `ty check` to test all files or `ty check path/to/file.py` to test a specific file.
+  [Install ty](https://docs.astral.sh/ty/installation/) and then please use the command `ty check` to test all files or `ty check path/to/file.py` to test a specific file.
 
 - [__List comprehensions and generators__](https://docs.python.org/3/tutorial/datastructures.html#list-comprehensions) are preferred over the use of `lambda`, `map`, `filter`, `reduce` but the important thing is to demonstrate the power of Python in code that is easy to read and maintain.
 

backtracking/crossword_puzzle_solver.py

@@ -6,29 +6,28 @@ def is_valid(
 ) -> bool:
     """
     Check if a word can be placed at the given position.
+    A cell is valid if it is empty or already contains the correct letter
+    (enabling crossing/intersection between words).
 
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
+    >>> puzzle = [['', '', '', ''], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
     >>> is_valid(puzzle, 'word', 0, 0, True)
     True
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
     >>> is_valid(puzzle, 'word', 0, 0, False)
     True
+    >>> puzzle2 = [['w', '', ''], ['o', '', ''], ['r', '', ''], ['d', '', '']]
+    >>> is_valid(puzzle2, 'word', 0, 0, True)
+    True
+    >>> is_valid(puzzle2, 'cat', 0, 0, True)
+    False
     """
-    for i in range(len(word)):
-        if vertical:
-            if row + i >= len(puzzle) or puzzle[row + i][col] != "":
-                return False
-        elif col + i >= len(puzzle[0]) or puzzle[row][col + i] != "":
+    rows, cols = len(puzzle), len(puzzle[0])
+    for i, ch in enumerate(word):
+        r, c = (row + i, col) if vertical else (row, col + i)
+        if r >= rows or c >= cols:
+            return False
+        cell = puzzle[r][c]
+        if cell not in ("", ch):
             return False
     return True
 
@@ -37,95 +36,87 @@ def place_word(
     puzzle: list[list[str]], word: str, row: int, col: int, vertical: bool
 ) -> None:
     """
-    Place a word at the given position.
-
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
+    Place a word at the given position in the puzzle.
+
+    >>> puzzle = [['', '', '', ''], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
     >>> place_word(puzzle, 'word', 0, 0, True)
     >>> puzzle
     [['w', '', '', ''], ['o', '', '', ''], ['r', '', '', ''], ['d', '', '', '']]
     """
-    for i, char in enumerate(word):
+    for i, ch in enumerate(word):
         if vertical:
-            puzzle[row + i][col] = char
+            puzzle[row + i][col] = ch
         else:
-            puzzle[row][col + i] = char
+            puzzle[row][col + i] = ch
 
 
 def remove_word(
-    puzzle: list[list[str]], word: str, row: int, col: int, vertical: bool
+    puzzle: list[list[str]],
+    word: str,
+    row: int,
+    col: int,
+    vertical: bool,
+    snapshot: list[list[str]],
 ) -> None:
     """
-    Remove a word from the given position.
-
-    >>> puzzle = [
-    ...     ['w', '', '', ''],
-    ...     ['o', '', '', ''],
-    ...     ['r', '', '', ''],
-    ...     ['d', '', '', '']
-    ... ]
-    >>> remove_word(puzzle, 'word', 0, 0, True)
+    Remove a word from the puzzle, restoring only cells that were empty
+    before placement. Cells shared with crossing words are preserved.
+
+    >>> puzzle = [['w', 'o', 'r', 'd'], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
+    >>> snap = [['', 'o', 'r', 'd'], ['', '', '', ''],
+    ...         ['', '', '', ''], ['', '', '', '']]
+    >>> remove_word(puzzle, 'word', 0, 0, False, snap)
     >>> puzzle
-    [['', '', '', ''], ['', '', '', ''], ['', '', '', ''], ['', '', '', '']]
+    [['', 'o', 'r', 'd'], ['', '', '', ''], ['', '', '', ''], ['', '', '', '']]
     """
     for i in range(len(word)):
-        if vertical:
-            puzzle[row + i][col] = ""
-        else:
-            puzzle[row][col + i] = ""
+        r, c = (row + i, col) if vertical else (row, col + i)
+        if snapshot[r][c] == "":
+            puzzle[r][c] = ""
 
 
 def solve_crossword(puzzle: list[list[str]], words: list[str]) -> bool:
     """
     Solve the crossword puzzle using backtracking.
+    Words are tried longest-first to prune the search space early.
+    Intersections between words (shared letters) are supported.
 
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
-
-    >>> words = ['word', 'four', 'more', 'last']
-    >>> solve_crossword(puzzle, words)
+    >>> puzzle = [['', '', '', ''], ['', '', '', ''],
+    ...           ['', '', '', ''], ['', '', '', '']]
+    >>> solve_crossword(puzzle, ['word', 'four', 'more', 'last'])
     True
-    >>> puzzle = [
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', ''],
-    ...     ['', '', '', '']
-    ... ]
-    >>> words = ['word', 'four', 'more', 'paragraphs']
-    >>> solve_crossword(puzzle, words)
+    >>> puzzle2 = [['', '', '', ''], ['', '', '', ''],
+    ...            ['', '', '', ''], ['', '', '', '']]
+    >>> solve_crossword(puzzle2, ['word', 'four', 'more', 'paragraphs'])
     False
     """
+    if not words:
+        return True
+
+    remaining = sorted(words, key=len, reverse=True)
+    word, rest = remaining[0], remaining[1:]
+
     for row in range(len(puzzle)):
         for col in range(len(puzzle[0])):
-            if puzzle[row][col] == "":
-                for word in words:
-                    for vertical in [True, False]:
-                        if is_valid(puzzle, word, row, col, vertical):
-                            place_word(puzzle, word, row, col, vertical)
-                            words.remove(word)
-                            if solve_crossword(puzzle, words):
-                                return True
-                            words.append(word)
-                            remove_word(puzzle, word, row, col, vertical)
-                return False
-    return True
+            for vertical in (True, False):
+                if is_valid(puzzle, word, row, col, vertical):
+                    snapshot = [r[:] for r in puzzle]
+                    place_word(puzzle, word, row, col, vertical)
+                    if solve_crossword(puzzle, rest):
+                        return True
+                    remove_word(puzzle, word, row, col, vertical, snapshot)
+
+    return False
 
 
 if __name__ == "__main__":
     PUZZLE = [[""] * 3 for _ in range(3)]
     WORDS = ["cat", "dog", "car"]
-
     if solve_crossword(PUZZLE, WORDS):
         print("Solution found:")
         for row in PUZZLE:
-            print(" ".join(row))
+            print(" ".join(cell or "." for cell in row))
     else:
-        print("No solution found:")
+        print("No solution found.")

bit_manipulation/count_number_of_one_bits.py

@@ -64,27 +64,76 @@ def get_set_bits_count_using_modulo_operator(number: int) -> int:
     return result
 
 
+def get_set_bits_count_using_lookup_table(number: int) -> int:
+    """
+    Count the number of set bits in a 32-bit integer using a precomputed lookup table.
+
+    I see similar approach in GeeksforGeeks, but the implementation is different.
+    Link to Code:
+    https://www.geeksforgeeks.org/dsa/count-set-bits-integer-using-lookup-table/
+
+    >>> get_set_bits_count_using_lookup_table(25)
+    3
+    >>> get_set_bits_count_using_lookup_table(37)
+    3
+    >>> get_set_bits_count_using_lookup_table(21)
+    3
+    >>> get_set_bits_count_using_lookup_table(58)
+    4
+    >>> get_set_bits_count_using_lookup_table(0)
+    0
+    >>> get_set_bits_count_using_lookup_table(256)
+    1
+    >>> get_set_bits_count_using_lookup_table(-1)
+    Traceback (most recent call last):
+        ...
+    ValueError: the value of input must not be negative
+    """
+    _lookup_table = [bin(i).count("1") for i in range(256)]
+
+    if number < 0:
+        raise ValueError("the value of input must not be negative")
+
+    # Split 32-bit number into four 8-bit chunks and use lookup table
+    return (
+        _lookup_table[number & 0xFF]
+        + _lookup_table[(number >> 8) & 0xFF]
+        + _lookup_table[(number >> 16) & 0xFF]
+        + _lookup_table[(number >> 24) & 0xFF]
+    )
+
+
 def benchmark() -> None:
     """
-    Benchmark code for comparing 2 functions, with different length int values.
-    Brian Kernighan's algorithm is consistently faster than using modulo_operator.
+    Benchmark code for comparing 3 functions, with different length int values.
+    Brian Kernighan's algorithm is consistently faster than using modulo_operator,
+    and the lookup table method is often the fastest for repeated calls.
     """
 
     def do_benchmark(number: int) -> None:
         setup = "import __main__ as z"
         print(f"Benchmark when {number = }:")
+
         print(f"{get_set_bits_count_using_modulo_operator(number) = }")
         timing = timeit(
             f"z.get_set_bits_count_using_modulo_operator({number})", setup=setup
         )
         print(f"timeit() runs in {timing} seconds")
+
         print(f"{get_set_bits_count_using_brian_kernighans_algorithm(number) = }")
         timing = timeit(
             f"z.get_set_bits_count_using_brian_kernighans_algorithm({number})",
             setup=setup,
         )
         print(f"timeit() runs in {timing} seconds")
 
+        print(f"{get_set_bits_count_using_lookup_table(number) = }")
+        timing = timeit(
+            f"z.get_set_bits_count_using_lookup_table({number})",
+            setup=setup,
+        )
+        print(f"timeit() runs in {timing} seconds")
+
     for number in (25, 37, 58, 0):
         do_benchmark(number)
         print()

blockchain/diophantine_equation.py

@@ -100,6 +100,64 @@ def extended_gcd(a: int, b: int) -> tuple[int, int, int]:
     return (d, x, y)
 
 
+def all_diophantine_solutions(
+    a: int,
+    b: int,
+    c: int,
+    n: int = 2,
+) -> list[tuple[int, int]]:
+    """
+    Return up to `n` integer solutions (x, y) to the linear Diophantine equation
+    a*x + b*y = c using the extended Euclidean algorithm.
+
+    Raises
+    ------
+    ValueError
+        If no integer solutions exist.
+
+    Time complexity
+    ---------------
+    O(log(max(|a|, |b|))) to compute a base solution using extended_gcd;
+    plus O(n) to enumerate `n` solutions.
+
+    Space complexity
+    ----------------
+    O(1) beyond the returned list.
+
+    Examples
+    --------
+    >>> all_diophantine_solutions(10, 6, 14, n=2)
+    [(-7, 14), (-4, 9)]
+    >>> all_diophantine_solutions(10, 6, 14, n=4)
+    [(-7, 14), (-4, 9), (-1, 4), (2, -1)]
+    >>> all_diophantine_solutions(3, 6, 10, n=1)
+    Traceback (most recent call last):
+    ...
+    ValueError: No integer solutions exist for a=3, b=6, c=10
+    """
+    if a == 0 and b == 0:
+        if c == 0:
+            # Infinite solutions; return one canonical solution.
+            return [(0, 0)][: min(1, n)]
+        raise ValueError("No integer solutions exist for a=0, b=0, c!=0")
+
+    g, xg, yg = extended_gcd(abs(a), abs(b))
+    if c % g != 0:
+        msg = f"No integer solutions exist for a={a}, b={b}, c={c}"
+        raise ValueError(msg)
+
+    # Scale a particular solution to ax + by = c
+    x0, y0 = xg * (c // g), yg * (c // g)
+    if a < 0:
+        x0 = -x0
+    if b < 0:
+        y0 = -y0
+
+    # General solution: x = x0 + t*(b/g), y = y0 - t*(a/g)
+    dx, dy = b // g, a // g
+    return [(x0 + t * dx, y0 - t * dy) for t in range(n)]
+
+
 if __name__ == "__main__":
     from doctest import testmod
 

conversions/excel_title_to_column.py

@@ -12,8 +12,24 @@ def excel_title_to_column(column_title: str) -> int:
     28
     >>> excel_title_to_column("Z")
     26
+    >>> excel_title_to_column("a")
+    1
+    >>> excel_title_to_column("ab")
+    28
+    >>> excel_title_to_column("")
+    Traceback (most recent call last):
+        ...
+    ValueError: Column title must contain only alphabetic characters.
+    >>> excel_title_to_column("A1")
+    Traceback (most recent call last):
+        ...
+    ValueError: Column title must contain only alphabetic characters.
     """
-    assert column_title.isupper()
+    if not column_title or not column_title.isalpha():
+        msg = "Column title must contain only alphabetic characters."
+        raise ValueError(msg)
+
+    column_title = column_title.upper()
     answer = 0
     index = len(column_title) - 1
     power = 0