Merge pull request #53 from junnengsoo/branch-binarySearch

Branch binary search

Author: 4ndrelim

docs/assets/images/BinarySearchTemplated1.jpeg

@@ -10,52 +10,100 @@ Two versions of binary search has been implemented in this repository - BinarySe
 Image Source: GeeksforGeeks
 
 BinarySearch is a more straightforward and intuitive version of the binary search algorithm. In this approach, after the
-mid-value is calculated, the high and low pointers are adjusted by just one unit. From the above example, after mid 
-points to index 4 in the first search, the low pointer moves to index 5 (+1) when narrowing the search. Similarly, when 
-mid points to index 7 in the second search, the high pointer shifts to index 6 (-1) when narrowing the search. This
-prevents any possibility of infinite loops.
+mid-value is calculated, the high or low pointer is adjusted by just one unit. From the above example, after mid points 
+to index 4 in the first search, the low pointer moves to index 5 (+1 from 4) when narrowing the search. Similarly, when 
+mid points to index 7 in the second search, the high pointer shifts to index 6 (-1 from 7) when narrowing the search. 
+This prevents any possibility of infinite loops. During the search, the moment mid-value is equal to the target value, 
+the search ends prematurely. Note that there is no need for a "condition" method as the condition is already captured
+in the predicates of the if-else blocks.
 
 ## BinarySearchTemplated
 
 BinarySearchTemplated removes the condition that checks if the current mid-value is equal to the target (which helps to
 end the search the moment the target is found). The template adds a "condition" method which will be modified based on
 the requirements of the implementation.
 
-The narrowing of the search space differs from BinarySearch - only one of the high or low pointers will be adjusted by
-one unit.
+The narrowing of the search space differs from BinarySearch - only the high pointer will be adjusted by one unit.
 
 This template will work for most binary search problems and will only require the following changes:
 - Search space (high and low)
 - Condition method
 - Returned value (low or low - 1)
 
 ### Search Space (Requires change)
-Simply modify the initialisation of the high and low pointer according to the search space.
+Simply modify the initialisation of the high and low pointer according to the [search space](#search-space-adjustment).
 
 ### Condition (Requires change)
 We assume that when the condition returns true, the current value "passes" and when the condition returns false, the 
 current value "fails".
 
-In this template, we want to find the first "pass" in the array.
-
-INSERT IMAGE OF FIRST PASS
+Note that in this template, the conditional blocks
+```
+if (condition(x)) {
+   high = mid;
+} else {
+   low = mid + 1;
+}
+```
+requires elements that "fail" the condition to be on the left of the elements that "pass" the condition, see below, in a
+sorted array due to the way the high and low pointers are reassigned.
+
+![binary search templated 1 img](../../../../../docs/assets/images/BinarySearchTemplated1.jpeg)
+
+Hence, we will need to implement a condition method that is able to discern between arrays that "pass" and "fail"
+accurately and also place them in the correct relative positions i.e. "fail" on the left of "pass". Suppose we change 
+the condition method implementation in BinarySearchTemplated from `value >= target` to `value <= target`, what will 
+happen? 
+<details>
+<summary> <b>what will happen?</b> </summary>
+The array becomes "P P F F F F" and the low and high pointers are now reassigned wrongly.
+</details>
 
 ### Returned Value (Requires change)
-In the implementation of BinarySearchTemplated, return low was used to find the first "pass".
+In this implementation of BinarySearchTemplated, we return the first "pass" in the array with `return low`. This is
+because our condition method implementation encompasses the target value that we are finding i.e. when 
+`value == target`.
+
+```java
+public static boolean condition(int value, int target) {
+    return value >= target;
+}
+```
+![binary search templated 1 img](../../../../../docs/assets/images/BinarySearchTemplated2.jpeg)
+
+However, if we want to return the last "fail" in the array, we will `return low - 1`.
+
+Suppose now we modify the condition to be `value > target`, how can we modify our BinarySearchTemplated to still work as
+expected?
+<details>
+<summary> <b>value > target?</b> </summary>
+Replace `return low` with `return low - 1` and replace arr[low] with arr[low - 1] as now the target value is the last 
+"fail".
+</details>
 
-EXPLANATION TBC, STILL THINKING HOW TO PHRASE IT.
 
 ### Search Space Adjustment
-What should be the search space adjustment? (Why only low = mid + 1)
+What should be the search space adjustment? Why is only low reassigned with an increment and not high?
+
+Due to the nature of floor division in Java's \ operator, if there are two mid-values within the search range, which is
+when the number of elements is even, the first mid-value will be selected. Suppose we do not increment the low pointer
+during reassignment, `low = mid`, let us take a look at the following example:
+
+![binary search templated 1 img](../../../../../docs/assets/images/BinarySearchTemplated3.jpeg)
+
+The search space has been narrowed down to the range of index 1 (low) to 2 (high). The mid-value is calculated, 
+`mid = (1 + 2) / 2`, to be 1 due to floor division. Since `2 < 5`, we enter the else block where there is reassignment 
+of `low = mid`. This means that the low pointer is still pointing to index 1 and the high pointer remains unchanged at
+index 2. This results in an infinite loop as the search range is not narrowed down.
 
-Due to the nature of floor division in Java's \ operator, the searched mid-index will always be smaller than the high
-pointer of the previous search range. On the other hand, low = mid + 1, ensures that the searched mid-index is always
-larger than the low pointer of the previous search range. This ensures that the search range is narrowed in every loop
-and prevents the possibility of infinite loops.
+To resolve this issue, we need `low = mid + 1`, which will result in the low pointer pointing to index 2 in this 
+scenario. We still ensure correctness because the mid-value is not the target value, as the mid-value < target, and we 
+can safely exclude it from the search range.
 
-INSERT IMAGE HERE TO EXPLAIN
+Why do we not need to increment the high pointer during reassignment? This is because the mid-value could be the target
+as the condition implemented is `value >= target`, hence, we cannot exclude it from the search range.
 
-As we close in towards the target value, the final low = mid + 1 narrows the search range from low. TBC ON EXPLANATION
+See [here](./binarySearchTemplatedExamples/README.md) to use the template for other problems
 
 Credits: [Powerful Ultimate Binary Search Template](https://leetcode.com/discuss/general-discussion/786126/python-powerful-ultimate-binary-search-template-solved-many-problems)
 

docs/assets/images/BinarySearchTemplated2.jpeg

@@ -0,0 +1,203 @@
+# BinarySearchTemplated Examples
+
+We will be utilising the BinarySearchTemplated implementation to solve some problems. 
+
+The following will differ between problems:
+- Search Space
+- Condition
+- Returned Value
+
+<b> How do we know if a problem can be solved with this template? </b>
+
+A problem is well-suited for this approach when it meets the following criteria:
+
+- <b> Clear Distinction Between Categories: </b> There should be a definitive way to categorize elements into two 
+groups: "pass" and "fail".
+
+- <b> Grouped Categories: </b> All the elements in one category should be grouped together without interspersion. This 
+implies that if we move from a "fail" element to a "pass" one, all subsequent elements will be "pass".
+
+- <b> Monotonic Property: </b> There needs to be a consistent, unidirectional trend or property in the search space. 
+This means the condition being checked either consistently increases or decreases. For the classical binary search on a 
+sorted array, this monotonic property is the sorted order of the elements, where the array elements increase 
+(or decrease) consistently.
+
+## 1. First Bad Version [Easy]
+
+### Problem:
+
+You are a product manager and currently leading a team to develop a new product. Unfortunately, the latest version of 
+your product fails the quality check. Since each version is developed based on the previous version, all the versions 
+after a bad version are also bad.
+
+Suppose you have `n` versions `[1, 2, ..., n]` and you want to find out the first bad one, which causes all the 
+following ones to be bad.
+
+You are given an API bool `isBadVersion(version)` which returns whether `version` is bad. Implement a function to find 
+the first bad version. You should minimize the number of calls to the API.
+
+Example 1:
+```
+Input: n = 5, bad = 4
+Output: 4
+Explanation:
+call isBadVersion(3) -> false
+call isBadVersion(5) -> true
+call isBadVersion(4) -> true
+Then 4 is the first bad version.
+```
+
+### Solution:
+
+<b> Search Space </b>
+
+The search space includes all possible values.
+
+```java
+high = n - 1;
+low = 0;
+```
+
+<b> Condition </b>
+
+The condition has already been implemented. But we need to check if the elements that pass the condition will be on the
+right of those that fail! Since "all the versions after a bad version are also bad", our template will work.
+
+<b> Returned Value </b>
+
+Since we want to return the first bad version, we will return low.
+
+![first bad version img](../../../../../../docs/assets/images/firstBadVersion.jpeg)
+
+<b> Full Solution: </b>
+
+```java
+public int firstBadVersion(int n) {
+    int high = n - 1; // max index for n elements
+    int low = 0;
+    while (low < high) {
+        int mid = low + (high - low) / 2;
+        if (isBadVersion(mid)) { // condition is isBadVersion
+            high = mid;
+        } else {
+            low = mid + 1;
+        }
+    }
+    
+    return low; // return first "pass"
+}
+```
+
+## 2. Capacity To Ship Packages Within D Days [Medium]
+
+### Problem:
+
+A conveyor belt has packages that must be shipped from one port to another within `days` days.
+
+The `ith` package on the conveyor belt has a weight of `weights[i]`. Each day, we load the ship with packages on the 
+conveyor belt (in the order given by `weights`). We may not load more weight than the maximum weight capacity of the 
+ship.
+
+Return the least weight capacity of the ship that will result in all the packages on the conveyor belt being shipped 
+within `days` days.
+
+Example 1:
+```
+Input: weights = [1,2,3,4,5,6,7,8,9,10], days = 5
+Output: 15
+Explanation: A ship capacity of 15 is the minimum to ship all the packages in 5 days like this:
+1st day: 1, 2, 3, 4, 5
+2nd day: 6, 7
+3rd day: 8
+4th day: 9
+5th day: 10
+
+Note that the cargo must be shipped in the order given, so using a ship of capacity 14 and splitting the packages into 
+parts like (2, 3, 4, 5), (1, 6, 7), (8), (9), (10) is not allowed.
+```
+
+### Solution:
+
+On first glance, while we are given an array, simply binary searching the array does not solve the problem. However,
+since our goal is to determine the least weight capacity of the ship, could this be our "target"? The answer is yes.
+By having each element being a least weight capacity case, with the lowest index being the heaviest weight and the 
+highest index being the sum of all weights, we will have our search space. The monotonic property present is that if
+we can ship all packages within `D` days with capacity `m`, we can definitely ship them within `D` days with any
+capacity greater than `m`, such as `m + 1`.
+
+<b> Search Space </b>
+
+The search space is the range of least weight capacity we should search. The minimum least weight capacity that must be
+required is the heaviest package as we cannot split the heaviest package. The maximum least weight capacity that is
+necessary is the sum of all weights - i.e. we have to ship all packages within `1` day.
+
+```java
+int sum = 0;
+for (i = 0; i < weights.length; i++) {
+    sum += weights[i];
+}
+high = sum;
+low = weights[weights.length - 1];
+```
+
+<b> Condition </b>
+
+The condition is to check if it is feasible to ship all packages within `D` days with a least weight capacity of `m`.
+Where `D` is given and `m` is the mid-value in our search range.
+
+```java
+public static boolean isFeasible(int[] weights, int days, int capacity) {
+    int daysNeeded = 1;
+    int currentWeight = 0;
+    for (int i = 0; i < weights.length; i++) {
+        if (currentWeight + weights[i] > capacity) {
+            daysNeeded++;
+            currentWeight = 0; // Reset current weight as we are starting a new day
+        }
+        currentWeight += weights[i];
+    }
+    return daysNeeded <= days; // If days needed is less than or equal to days, it is feasible
+}
+```
+
+<b> Returned Value </b>
+
+Since we want to return the minimum least weight capacity where we can deliver in time, we will return low.
+
+<b> Full Solution: </b>
+
+```java
+public int shipWithinDays(int[] weights, int days) {
+    public boolean isFeasible(int[] weights, int days, int capacity) {
+        int daysNeeded = 1;
+        int currentWeight = 0;
+        for (int i = 0; i < weights.length; i++) {
+            if (currentWeight + weights[i] > capacity) {
+                daysNeeded++;
+                currentWeight = 0; // Reset current weight as we are starting a new day
+            }
+            currentWeight += weights[i];
+        }
+        return daysNeeded <= days;
+    }
+    
+    int sum = 0;
+    for (i = 0; i < weights.length; i++) {
+        sum += weights[i];
+    }
+    
+    high = sum;
+    low = weights[weights.length - 1];
+    
+    while (low < high) {
+        int mid = low + (high - low) / 2;
+        if (isFeasible(weights, days, mid)) { // condition is isFeasible
+            high = mid;
+        } else {
+            low = mid + 1;
+        }
+    }
+    
+    return low; // return first "pass"
+}
+```