Merge branch 'main' into subtract-two-numbers

.github/PULL_REQUEST_TEMPLATE.md

@@ -54,8 +54,10 @@ about: A template PR for code review with a checklist
 
 - [ ] The function's name describes it's behavior
 - [ ] The function's name matches the file name
+  - _It's ok to have extra helper functions if necessary, like with mergesort_
 - [ ] The function has correct type annotations
-- [ ] The function is not called in the function file
+- [ ] The function is not called at the top level of the function file 
+  - _Recursive solutions **can** call the function from **inside** the function body_
 
 ## Strategy
 
@@ -67,7 +69,7 @@ about: A template PR for code review with a checklist
 
 ### Don'ts
 
-- [ ] The function's strategy _is not_ described in the documentation
+- [ ] The function's strategy _is not_ described in any docstrings or tests
 - [ ] Comments explain the _strategy_, **not** the _implementation_
 - [ ] The function _does not_ have more comments than code
   - If it does, consider finding a new strategy or a simpler implementation

solutions/is_palindrome.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+A module for checking if an integer is a palindrome.
+
+Module contents:
+    - is_palindrome: Determines whether a given integer is a palindrome.
+
+Created on 12 31 2024
+@author: Muhammet Isik
+"""
+
+
+def is_palindrome(x: int) -> bool:
+    """
+    Checks if an integer is a palindrome.
+
+    An integer is a palindrome if it reads the same backward as forward.
+
+    Parameters:
+        x (int): An integer in the range [-2**31, 2**31 - 1].
+
+    Returns:
+        bool: True if the integer is a palindrome, False otherwise.
+
+    Raises:
+        AssertionError: If the input is not an integer or out of range.
+
+    Examples:
+        >>> is_palindrome(121)
+        True
+
+        >>> is_palindrome(-121)
+        False
+
+        >>> is_palindrome(10)
+        False
+
+        >>> is_palindrome(0)
+        True
+
+        >>> is_palindrome(12321)
+        True
+    """
+    # Defensive assertions
+    assert isinstance(x, int), "Input must be an integer."
+    assert -(2**31) <= x <= 2**31 - 1, "Input is outside the valid range."
+
+    # Convert the integer to its string representation
+    original_str = str(x)
+
+    # Reverse the string and compare it to the original
+    reversed_str = original_str[::-1]
+
+    # Return whether the original and reversed strings match
+    return original_str == reversed_str

solutions/is_power_of_two.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+A module for determining whether a given integer is a power of two.
+
+Module contents:
+    - is_power_of_two(n): Function to determine if `n` is a power of two.
+
+Created on 2024-12-31
+@author: Gennadii Ershov
+"""
+
+
+def is_power_of_two(n: int) -> bool:
+    """
+    Determines whether a given integer is a power of two.
+
+    Parameters:
+        n: int
+            An integer to check if it is a power of two.
+            Must satisfy the constraint: -2^31 <= n <= 2^31 - 1.
+
+    Returns -> bool:
+        True if the input is a power of two, False otherwise.
+
+    Raises:
+        AssertionError: if the input is not an integer or a float.
+        AssertionError: If the input number is not within the valid range (-2^31 <= n <= 2^31 - 1).
+
+    >>> is_power_of_two(1)
+    True
+
+    >>> is_power_of_two(16)
+    True
+
+    >>> is_power_of_two(3)
+    False
+    """
+
+    # The input number should be an integer
+    assert isinstance(n, (int, float)), "Given number must be an integer or a float"
+
+    # The input number should be within the valid range constraint: -2^31 <= n <= 2^31 - 1
+    assert (
+        -(2**31) <= n <= 2**31 - 1
+    ), f"Input must satisfy -2^31 <= n <= 2^31 - 1, but got {n}"
+
+    # Negative numbers and 0 cannot be powers of two
+    if n <= 0:
+        return False
+
+    # Odd numbers (except 1) are not powers of two
+    if n % 2 != 0 and n != 1:
+        return False
+
+    # Use a loop to check for powers of two
+    power = 1
+    while power < n:
+        power *= 2
+    return power == n

solutions/tests/test_is_palindrome.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Unit tests for the is_palindrome function.
+
+This module tests the `is_palindrome` function with standard, edge, and defensive cases.
+
+Created on 12 31 2024
+"""
+
+import unittest
+
+from ..is_palindrome import is_palindrome
+
+
+class TestIsPalindrome(unittest.TestCase):
+    """
+    Test suite for the is_palindrome function.
+
+    Ensures the function handles valid, edge, and invalid inputs correctly.
+    """
+
+    # Standard Cases
+    def test_positive_palindrome(self):
+        """Return True for numeric palindromes."""
+        self.assertTrue(is_palindrome(121))
+
+    def test_non_palindrome(self):
+        """Return False for non-palindromic numbers."""
+        self.assertFalse(is_palindrome(123))
+
+    def test_single_digit(self):
+        """Return True for single-digit numbers."""
+        self.assertTrue(is_palindrome(5))
+
+    # Edge Cases
+    def test_negative_number(self):
+        """Return False for negative numbers."""
+        self.assertFalse(is_palindrome(-121))
+
+    def test_zero(self):
+        """Return True for zero."""
+        self.assertTrue(is_palindrome(0))
+
+    # Defensive Cases - Each `AssertionError` gets its own test
+    def test_raise_for_string(self):
+        """Raise AssertionError for string input."""
+        with self.assertRaises(AssertionError):
+            is_palindrome("123")
+
+    def test_raise_for_float(self):
+        """Raise AssertionError for float input."""
+        with self.assertRaises(AssertionError):
+            is_palindrome(121.0)
+
+    def test_raise_for_none(self):
+        """Raise AssertionError for None input."""
+        with self.assertRaises(AssertionError):
+            is_palindrome(None)
+
+    def test_raise_for_out_of_range_positive(self):
+        """Raise AssertionError for out-of-range positive integer."""
+        with self.assertRaises(AssertionError):
+            is_palindrome(2**31)
+
+    def test_raise_for_out_of_range_negative(self):
+        """Raise AssertionError for out-of-range negative integer."""
+        with self.assertRaises(AssertionError):
+            is_palindrome(-(2**31) - 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

solutions/tests/test_is_power_of_two.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Test module for is_power_of_two function.
+
+Test categories:
+    - Standard cases: typical inputs such as small powers of two and non-powers of two.
+    - Edge cases: inputs like zero, negative numbers, valid floats (e.g., 16.0), boundary number.
+    - Defensive tests: invalid input types such as strings, lists, and other assertions.
+
+Created on 2024-12-31
+@author: Gennadii Ershov
+"""
+
+import unittest
+
+from ..is_power_of_two import is_power_of_two
+
+
+class TestIsPowerOfTwo(unittest.TestCase):
+    """Test the is_power_of_two function"""
+
+    # Standard test cases
+    def test_single_is_power_of_two(self):
+        """Test if n = 1 is correctly identified as a power of two."""
+        self.assertTrue(is_power_of_two(1))
+
+    def test_large_power_of_two(self):
+        """Test if n = 16 is correctly identified as a power of two."""
+        self.assertTrue(is_power_of_two(16))
+
+    def test_non_power_of_two(self):
+        """Test if n = 3 is correctly identified as not a power of two."""
+        self.assertFalse(is_power_of_two(3))
+
+    # Edge cases
+    def test_zero(self):
+        """Test if n = 0 is correctly identified as not a power of two."""
+        self.assertFalse(is_power_of_two(0))
+
+    def test_negative_number(self):
+        """Test if n = -2 is correctly identified as not a power of two."""
+        self.assertFalse(is_power_of_two(-2))
+
+    def test_float_power_of_two(self):
+        """Test if n = 16.0 is correctly identified as a power of two."""
+        self.assertTrue(is_power_of_two(16.0))
+
+    def test_float_non_power_of_two(self):
+        """Test if n = 3.5 is correctly identified as not a power of two."""
+        self.assertFalse(is_power_of_two(3.5))
+
+    def test_large_power_of_two_boundary(self):
+        """Test if n = 2^30 is correctly identified as a power of two."""
+        self.assertTrue(is_power_of_two(2**30))
+
+    # Defensive tests
+    def test_invalid_type_string(self):
+        """Test if a string raises an AssertionError."""
+        with self.assertRaises(AssertionError):
+            is_power_of_two("16")
+
+    def test_invalid_type_list(self):
+        """Test if a list raises an AssertionError."""
+        with self.assertRaises(AssertionError):
+            is_power_of_two([16])
+
+    def test_out_of_range_upper(self):
+        """Test if a value greater than 2^31 - 1 raises an AssertionError."""
+        with self.assertRaises(AssertionError):
+            is_power_of_two(2**31)
+
+    def test_out_of_range_lower(self):
+        """Test if a value less than -2^31 raises an AssertionError."""
+        with self.assertRaises(AssertionError):
+            is_power_of_two(-(2**31) - 1)