unsorted array function

src/algorithms/search/twin-pointers/README.md

@@ -1,6 +1,19 @@
 # Twin Pointers
 
-The twin pointers method, also known as the two pointers method, is a searching algorithm that can be used on both 
+The twin pointers method, also known as the two pointers method, is a searching algorithm 
+that can be used on both sorted and unsorted numerical arrays/lists, depending on the intent of the function. 
+At its simplest form the twin pointer method employes two "pointers" that either move at different 
+speeds/from different starting positions in order to draw comparisons between values in order to 
+find some specified target. In the case that the array/list being searched through is sorted, 
+a common usage of the twin pointers is to have one at the starting and one at the ending position; 
+in this manner, moving the left pointer to the right can be assumed to increase its value while moving 
+the right pointer to the left can be assumed to do vice versa. In the case of an unsorted arrays/list, 
+the usage methods are generally much more varied based on what the characteristics of the intended 
+target of the search are.
+
+Note that any array can be sorted to easily use the twin pointer method by using the Array.sort method.
+However, the Array.sort method inherently has a time complexity of O(n log n), which can be undesirable
+in many cases when the desired time complexity of your solution is simply O(n).
 
 ![Binary Search](https://upload.wikimedia.org/wikipedia/commons/8/83/Binary_Search_Depiction.svg)
 
@@ -10,5 +23,5 @@ The twin pointers method, also known as the two pointers method, is a searching
 
 ## References
 
-- [Wikipedia](https://en.wikipedia.org/wiki/Binary_search_algorithm)
+- [GeeksForGeeks](https://www.geeksforgeeks.org/two-pointers-technique/)
-- [YouTube](https://www.youtube.com/watch?v=P3YID7liBug&index=29&list=PLLXdhg_r2hKA7DPDsunoDZ-Z769jWn4R8)
+- [YouTube](https://youtu.be/VEPCm3BCtik?si=rH9O1My7Ym_83FrR)

src/algorithms/search/twin-pointers/twinPointers.js

@@ -0,0 +1,74 @@
+import Comparator from '../../../utils/comparator/Comparator';
+
+/**
+ * Some twin pointer implementations.
+ *
+ * @param {*[]} sortedArray
+ * @param {*} seekElement
+ * @param {function(a, b)} [comparatorCallback]
+ * @return {[number, number]}
+ */
+
+// Example of a twin pointer application in a sorted array where we are seeking the indices of two elements that sum to equal the target.
+export function twinPointerSorted(sortedArray, seekElement, comparatorCallback) {
+  const comparator = new Comparator(comparatorCallback);
+
+  // These variables will be our pointers; since the array is sorted, we can set them to the left and rightmost elements.
+  let left = 0;
+  let right = sortedArray.length - 1
+
+  // If our left and right pointers have met then we have iterated through the entire array.
+  while (left < right) {
+    
+    /** 
+     * If our sum is less than the target then we can increase said sum but by increasing the left value; 
+     * since the array is sorted, this will always result in array[left] becoming a larger number.
+    */
+    if (comparator.lessThan(sortedArray[left] + sortedarray[right], seekElement)) {
+        left++;
+
+    // Same concept as before, only now we decrease our sum because it's greater than the target.    
+    } else if (comparator.greaterThan(sortedArray[left] + sortedarray[right], seekElement)) {
+        right--;
+    
+    // Assuming we have found our target, return left and right since they represent the indices that our correct sum is located at.
+    } else {
+        return [left, right]
+    }
+  }
+
+  // Return [0, 0] (an impossible answer due to our while loop) if we haven't found any combination of numbers that works.
+  return [0, 0];
+}
+
+// An example of a twin pointer method on an unsorted array.
+export function twinPointerUnsorted(sortedArray, seekElement, comparatorCallback) {
+    const comparator = new Comparator(comparatorCallback);
+  
+    // These variables will be our pointers; since the array is sorted, we can set them to the left and rightmost elements.
+    let left = 0;
+    let right = sortedArray.length - 1
+  
+    // If our left and right pointers have met then we have iterated through the entire array.
+    while (left < right) {
+      
+      /** 
+       * If our sum is less than the target then we can increase said sum but by increasing the left value; 
+       * since the array is sorted, this will always result in array[left] becoming a larger number.
+      */
+      if (comparator.lessThan(sortedArray[left] + sortedarray[right], seekElement)) {
+          left++;
+  
+      // Same concept as before, only now we decrease our sum because it's greater than the target.    
+      } else if (comparator.greaterThan(sortedArray[left] + sortedarray[right], seekElement)) {
+          right--;
+      
+      // Assuming we have found our target, return left and right since they represent the indices that our correct sum is located at.
+      } else {
+          return [left, right]
+      }
+    }
+  
+    // Return [0, 0] (an impossible answer due to our while loop) if we haven't found any combination of numbers that works.
+    return [0, 0];
+  }