From ea09be9f0d474b8ff8a87fc447a4c110aee09bd8 Mon Sep 17 00:00:00 2001
From: AgathaBahati <matinodev@gmail.com>
Date: Mon, 28 Oct 2024 15:39:47 +0300
Subject: [PATCH 1/2] feat: add happy number

---
 arrays_and_strings/happy_number/__init__.py   |  0
 .../happy_number/happy_number.py              | 19 +++++++++++++++++++
 2 files changed, 19 insertions(+)
 create mode 100644 arrays_and_strings/happy_number/__init__.py
 create mode 100644 arrays_and_strings/happy_number/happy_number.py

diff --git a/arrays_and_strings/happy_number/__init__.py b/arrays_and_strings/happy_number/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/arrays_and_strings/happy_number/happy_number.py b/arrays_and_strings/happy_number/happy_number.py
new file mode 100644
index 0000000..10fa4af
--- /dev/null
+++ b/arrays_and_strings/happy_number/happy_number.py
@@ -0,0 +1,19 @@
+def happy_number(n: int) -> bool:
+    slow = n
+    fast = squared_digits_sum(n)
+    
+    while fast != slow or n != 1:
+        slow = squared_digits_sum(slow)
+        fast = squared_digits_sum(squared_digits_sum(fast))
+        
+    if fast == slow:
+        return False
+    return True
+    
+def squared_digits_sum(n: int) -> int:
+    digits_sum = 0
+    while n > 0:
+        n, digit = divmod(n,10)
+        digits_squared = digit * digit
+        digits_sum += digits_squared
+    return digits_sum
\ No newline at end of file

From d938f9ed163292c44ba2a659372dce59799bd364 Mon Sep 17 00:00:00 2001
From: AgathaBahati <matinodev@gmail.com>
Date: Mon, 28 Oct 2024 15:53:43 +0300
Subject: [PATCH 2/2] doc: add comments and README

---
 arrays_and_strings/happy_number/README.md     | 65 +++++++++++++++++++
 .../happy_number/happy_number.py              | 52 +++++++++++++--
 2 files changed, 110 insertions(+), 7 deletions(-)
 create mode 100644 arrays_and_strings/happy_number/README.md

diff --git a/arrays_and_strings/happy_number/README.md b/arrays_and_strings/happy_number/README.md
new file mode 100644
index 0000000..4f4bb74
--- /dev/null
+++ b/arrays_and_strings/happy_number/README.md
@@ -0,0 +1,65 @@
+## **Problem Statement**
+
+Write an algorithm to determine if a number `n` is a happy number.
+
+We use the following process to check if a given number is a happy number:
+
+    - Starting with the given number n, replace the number with the sum of the squares of its digits.
+    - Repeat the process until:
+        - The number equals 1, which will depict that the given number n is a happy number.
+        - It enters a cycle, which will depict that the given number n is not a happy number.
+
+Return TRUE if `n` is a happy number, and FALSE if not.
+
+### Constraints
+
+> 1 ≤ n ≤ 2<sup>31</sup> - 1
+
+## **Examples**
+
+### Example 1: Determining a Happy Number
+
+**Input:** `n = 19`
+
+**Process:**
+
+1. Start with `n = 19`.
+2. Calculate the sum of the squares of its digits: $1^2 + 9^2 = 1 + 81 = 82$.
+3. Replace 19 with 82.
+4. Calculate the sum of the squares of the digits of 82: $8^2 + 2^2 = 64 + 4 = 68$.
+5. Replace 82 with 68.
+6. Calculate the sum of the squares of the digits of 68: $6^2 + 8^2 = 36 + 64 = 100$.
+7. Replace 68 with 100.
+8. Calculate the sum of the squares of the digits of 100: $1^2 + 0^2 + 0^2 = 1 + 0 + 0 = 1$.
+
+Since the process reaches 1, **19 is a happy number**.
+
+**Output:** `TRUE`
+
+### Example 2: Determining a Non-Happy Number
+
+**Input:** `n = 20`
+
+**Process:**
+
+1. Start with `n = 20`.
+2. Calculate the sum of the squares of its digits: $2^2 + 0^2 = 4 + 0 = 4$.
+3. Replace 20 with 4.
+4. Calculate the sum of the squares of the digits of 4: $4^2 = 16$.
+5. Replace 4 with 16.
+6. Calculate the sum of the squares of the digits of 16: $1^2 + 6^2 = 1 + 36 = 37$.
+7. Replace 16 with 37.
+8. Calculate the sum of the squares of the digits of 37: $3^2 + 7^2 = 9 + 49 = 58$.
+9. Replace 37 with 58.
+10. Calculate the sum of the squares of the digits of 58: $5^2 + 8^2 = 25 + 64 = 89$.
+11. Replace 58 with 89.
+12. Calculate the sum of the squares of the digits of 89: $8^2 + 9^2 = 64 + 81 = 145$.
+13. Replace 89 with 145.
+14. Calculate the sum of the squares of the digits of 145: $1^2 + 4^2 + 5^2 = 1 + 16 + 25 = 42$.
+15. Replace 145 with 42.
+16. Calculate the sum of the squares of the digits of 42: $4^2 + 2^2 = 16 + 4 = 20$.
+
+The process returns to 20, indicating a cycle. **20 is not a happy number**.
+
+**Output:** `FALSE`
+
diff --git a/arrays_and_strings/happy_number/happy_number.py b/arrays_and_strings/happy_number/happy_number.py
index 10fa4af..31342f0 100644
--- a/arrays_and_strings/happy_number/happy_number.py
+++ b/arrays_and_strings/happy_number/happy_number.py
@@ -1,19 +1,57 @@
 def happy_number(n: int) -> bool:
+    """
+    Determine if a number is a happy number.
+
+    A happy number is defined as a number which eventually reaches 1 when replaced by the sum of the square of each digit.
+    If it loops endlessly in a cycle that does not include 1, it is not a happy number.
+
+    Parameters:
+    n (int): The number to be checked.
+
+    Returns:
+    bool: True if the number is a happy number, False otherwise.
+
+    """
     slow = n
     fast = squared_digits_sum(n)
     
-    while fast != slow or n != 1:
+    while fast != slow:
         slow = squared_digits_sum(slow)
         fast = squared_digits_sum(squared_digits_sum(fast))
         
-    if fast == slow:
-        return False
-    return True
-    
+    return slow == 1
+
 def squared_digits_sum(n: int) -> int:
+    """
+    Calculate the sum of the squares of the digits of a number.
+
+    Parameters:
+    n (int): The number whose digits are to be squared and summed.
+
+    Returns:
+    int: The sum of the squares of the digits of the number.
+    """
     digits_sum = 0
     while n > 0:
-        n, digit = divmod(n,10)
+        n, digit = divmod(n, 10)
         digits_squared = digit * digit
         digits_sum += digits_squared
-    return digits_sum
\ No newline at end of file
+    return digits_sum
+
+# Approach and Reasoning:
+#     -----------------------
+#     - The function uses Floyd's Cycle Detection Algorithm (also known as the tortoise and hare algorithm) to detect cycles. Also known as fast and slow pointers.
+#     - Two pointers, `slow` and `fast`, are used to traverse the sequence of numbers generated by repeatedly replacing the number with the sum of the squares of its digits.
+#     - `slow` moves one step at a time (computes the sum of squares once), while `fast` moves two steps at a time (computes the sum of squares twice).
+#     - If there is a cycle (i.e., the number is not happy), `slow` and `fast` will eventually meet at the same number.
+#     - If the number is happy, the sequence will eventually reach 1, and the loop will terminate.
+
+#     Time Complexity:
+#     ----------------
+#     - The time complexity is O(log n), where n is the input number.
+#     - The time complexity is O(log_{10}(n)), where n is the input number. This complexity arises from the `squared_digits_sum` function, 
+#       as the number of digits in n is proportional to log_{10}(n), and each digit is processed in constant time.
+
+#     Space Complexity:
+#     -----------------
+#     - The space complexity is O(1) because only a constant amount of extra space is used for variables and function calls.

<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>pFad - Phonifier reborn</title>
<meta http-equiv='Content-Type' content='text/html; charset=utf-8' />
</head>
<body>
<h1>Pfad - The Proxy pFad of &#169; 2024 Garber Painting. All rights reserved.</h1>


<!-- Disclaimer -->
<p>Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.</p>
<br>
<p>Alternative Proxies:</p><p><a href="http://rainy.clevelandohioweatherforecast.com/php-proxy/index.php?q=https://patch-diff.githubusercontent.com/raw/MoigeMatino/data-structures-algorithms-python/pull/364.patch" target="_blank">Alternative Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/index.php?u=https://patch-diff.githubusercontent.com/raw/MoigeMatino/data-structures-algorithms-python/pull/364.patch" target="_blank">pFad Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v3index.php?u=https://patch-diff.githubusercontent.com/raw/MoigeMatino/data-structures-algorithms-python/pull/364.patch" target="_blank">pFad v3 Proxy</a></p><p><a href="http://rainy.clevelandohioweatherforecast.com/pFad/v4index.php?u=https://patch-diff.githubusercontent.com/raw/MoigeMatino/data-structures-algorithms-python/pull/364.patch" target="_blank">pFad v4 Proxy</a></p></body>
</html>