doc: add documentation and README

Author: MoigeMatino

arrays_and_strings/search_rotated_sorted_array/README.md

@@ -0,0 +1,92 @@
+## **Problem Statement**
+
+Given a sorted integer array, `nums`, and an integer value, `target`, the array is rotated by some arbitrary number. Search and return the index of `target` in this array. If the `target` does not exist, return `-1`.
+
+
+### Constraints
+- All values in nums are unique.
+- The values in nums are sorted in ascending order.
+- The array may have been rotated by some arbitrary number.
+- 1 ≤ nums.length ≤1000≤1000
+- −10<sup>4</sup> ≤ nums[i] ≤ 10<sup>4</sup>
+- −10<sup>4</sup> ≤ target ≤ 10<sup>4</sup>
+
+## **Examples**
+
+### Example 1: Target Found in Rotated Array
+
+**Input:**
+
+- `nums = [4, 5, 6, 7, 0, 1, 2]`
+- `target = 0`
+
+**Process:**
+- The array `[4, 5, 6, 7, 0, 1, 2]` is a sorted array that has been rotated.
+- The target value `0` is located at index `4`.
+
+**Output:** `4`
+
+**Visualization:**
+- Original Sorted Array: [0, 1, 2, 4, 5, 6, 7]
+- Rotated Array:         [4, 5, 6, 7, 0, 1, 2]
+- Target: 0
+- Index of Target: 4
+
+### Example 2: Target Not Found
+
+**Input:**
+- `nums = [4, 5, 6, 7, 0, 1, 2]`
+- `target = 3`
+
+**Process:**
+- The array `[4, 5, 6, 7, 0, 1, 2]` is a sorted array that has been rotated.
+- The target value `3` is not present in the array.
+
+**Output:** `-1`
+
+**Visualization:**
+
+Original Sorted Array: [0, 1, 2, 4, 5, 6, 7]
+Rotated Array:         [4, 5, 6, 7, 0, 1, 2]
+Target:                3
+Index of Target:       -1 (not found)
+
+
+### Example 3: Target Found at Beginning
+
+**Input:**
+- `nums = [6, 7, 0, 1, 2, 4, 5]`
+- `target = 6`
+
+**Process:**
+- The array `[6, 7, 0, 1, 2, 4, 5]` is a sorted array that has been rotated.
+- The target value `6` is located at index `0`.
+
+**Output:** `0`
+
+**Visualization:**
+
+- Original Sorted Array: [0, 1, 2, 4, 5, 6, 7]
+- Rotated Array:         [6, 7, 0, 1, 2, 4, 5]
+- Target:                6
+- Index of Target:       0
+
+
+### Example 4: Target Found at End
+
+**Input:**
+- `nums = [6, 7, 0, 1, 2, 4, 5]`
+- `target = 5`
+
+**Process:**
+- The array `[6, 7, 0, 1, 2, 4, 5]` is a sorted array that has been rotated.
+- The target value `5` is located at index `6`.
+
+**Output:** `6`
+
+**Visualization:**
+
+- Original Sorted Array: [0, 1, 2, 4, 5, 6, 7]
+- Rotated Array:         [6, 7, 0, 1, 2, 4, 5]
+- Target:                5
+- Index of Target:       6

arrays_and_strings/search_rotated_sorted_array/search_rotated_sorted_array_v1.py

@@ -1,21 +1,55 @@
 def search_rotated_sorted_array(nums: list[int], target: int) -> int:
+    """
+    Search for a target value in a rotated sorted array using an iterative binary search.
+
+    Parameters:
+    nums (list[int]): The rotated sorted array.
+    target (int): The target value to search for.
+
+    Returns:
+    int: The index of the target if found, otherwise -1.
+
+    """
     low = 0
     high = len(nums) - 1
 
     while low <= high:
-        mid = low + (high - low)//2
+        mid = low + (high - low) // 2
+        
+        # Check if the mid element is the target
         if nums[mid] == target:
             return mid
 
+        # Determine if the left half is sorted
         if nums[low] <= nums[mid]:
-            if nums[low] <= target and target <= nums[mid]:
+            # Check if the target is in the sorted left half
+            if nums[low] <= target <= nums[mid]:
                 high = mid - 1
             else:
                 low = mid + 1
-                
         else:
-            if nums[mid] <= target and target <= nums[high]:
+            # Check if the target is in the sorted right half
+            if nums[mid] <= target <= nums[high]:
                 low = mid + 1
             else:
                 high = mid - 1
-    return -1
+    
+    # Target not found
+    return -1
+
+# Approach and Rationale:
+#     -----------------------
+#     - This function uses an iterative binary search approach to find the target in a rotated sorted array.
+#     - A rotated sorted array is an array that was originally sorted in increasing order but then rotated at some pivot.
+#     - The key observation is that at least one half of the array (either left or right of the midpoint) is always sorted.
+#     - By comparing the target with the elements in the sorted half, we can decide which half to continue searching in.
+#     - This approach reduces the search space by half in each iteration, similar to binary search.
+
+#     Time Complexity:
+#     ----------------
+#     - The time complexity is O(log n), where n is the number of elements in the array.
+#     - This is because the search space is halved in each iteration, similar to binary search.
+
+#     Space Complexity:
+#     -----------------
+#     - The space complexity is O(1) because the algorithm uses a constant amount of extra space.

arrays_and_strings/search_rotated_sorted_array/search_rotated_sorted_array_v2.py

@@ -1,20 +1,53 @@
-def search_rotated_sorted_array(nums: list[int],low: int, high: int, target:int) -> int:
-    
+def search_rotated_sorted_array(nums: list[int], low: int, high: int, target: int) -> int:
+    """
+    Search for a target value in a rotated sorted array using a modified binary search.
+
+    Parameters:
+    nums (list[int]): The rotated sorted array.
+    low (int): The starting index of the search range.
+    high (int): The ending index of the search range.
+    target (int): The target value to search for.
+
+    Returns:
+    int: True if the target is found, False otherwise.
+
+    """
     if low >= high:
         return False
 
-    mid = low + (high - low)//2
+    mid = low + (high - low) // 2
 
     if nums[mid] == target:
         return True
 
+    # Check if the left half is sorted
     if nums[low] <= nums[mid]:
-        if nums[low] <= target and target <= nums[mid]:
-            return search_rotated_sorted_array(nums, low, mid-1, target)
+        # If target is in the sorted left half
+        if nums[low] <= target <= nums[mid]:
+            return search_rotated_sorted_array(nums, low, mid - 1, target)
         else:
-            return search_rotated_sorted_array(nums, mid+1, high, target)
+            return search_rotated_sorted_array(nums, mid + 1, high, target)
     else:
-        if nums[mid] <= target and target <= nums[high]:
-            return search_rotated_sorted_array(nums, mid+1, high, target)
+        # If target is in the sorted right half
+        if nums[mid] <= target <= nums[high]:
+            return search_rotated_sorted_array(nums, mid + 1, high, target)
         else:
-            return search_rotated_sorted_array(nums, low, mid-1, target)
+            return search_rotated_sorted_array(nums, low, mid - 1, target)
+        
+# Approach and Rationale:
+#     -----------------------
+#     - The function uses a recursive binary search approach to find the target in a rotated sorted array.
+#     - A rotated sorted array is an array that was originally sorted in increasing order but then rotated at some pivot.
+#     - The key observation is that at least one half of the array (either left or right of the midpoint) is always sorted.
+#     - By comparing the target with the elements in the sorted half, we can decide which half to continue searching in.
+#     - This approach reduces the search space by half in each recursive call, similar to binary search.
+
+#     Time Complexity:
+#     ----------------
+#     - The time complexity is O(log n), where n is the number of elements in the array.
+#     - This is because the search space is halved in each recursive call, similar to binary search.
+
+#     Space Complexity:
+#     -----------------
+#     - The space complexity is O(log n) due to the recursive call stack.
+#     - Each recursive call adds a new layer to the call stack, and the maximum depth of recursion is proportional to log n.