merging

Merge branch 'main' into branch-quickSort

Author: kaitinghh

README.md

@@ -8,19 +8,23 @@ This repository contains implementation of some of the fundamental data structur
 ## Full List of Implementation (in alphabetical order):
 ## Structures
 - Adelson-Velskii and Landis (AVL) Binary Search Tree
-- Disjoint Set
+- Disjoint Set / Union Find
     * Quick Find
-    * Weighted Union with path compression
+    * Weighted Union 
+    * Path compression
+- [Hashing](src/dataStructures/hashSet)
+    * [Chaining](src/dataStructures/hashSet/chaining/)
+    * [Open Addressing](src/dataStructures/hashSet/openAddressing/)
 - [Heap](src/dataStructures/heap/)
     * Max heap implementation
-- Linked List
+- [Linked List](src/dataStructures/linkedList)
 - LRU Cache
 - Minimum Spanning Tree
-- Queue
+- [Queue](src/dataStructures/queue)
 - Segment Tree
     * Array implementation
     * TreeNode implementation 
-- Stack
+- [Stack](src/dataStructures/stack)
 - Trie
 
 
@@ -47,11 +51,12 @@ This repository contains implementation of some of the fundamental data structur
 
 ## Short-cut to CS2040S Material
 1. Basic structures
-    * Linked List
-    * Stack
-    * Queue
+    * [Linked List](src/dataStructures/linkedList)
+    * [Stack](src/dataStructures/stack)
+    * [Queue](src/dataStructures/queue)
 2. Binary Search
     * Peak Finding
+    * Template
 3. Sorting
     * [Bubble](src/algorithms/sorting/bubbleSort)
     * [Insertion](src/algorithms/sorting/insertionSort)
@@ -64,9 +69,18 @@ This repository contains implementation of some of the fundamental data structur
     * Kd-tree
     * Interval tree
     * Augmented tree for orthogonal range searching
-5. Heap
+    * Red-Black Tree
+    * ab-Tree
+5. [Binary Heap](src/dataStructures/heap/)
+    * Max heap implementation
 6. Disjoint Set / Union Find
-7. Hashing
+    * Quick Find
+    * Weighted Union
+    * Path compression
+7. [Hashing](src/dataStructures/hashSet)
+    * [Chaining](src/dataStructures/hashSet/chaining/)
+    * [Open Addressing](src/dataStructures/hashSet/openAddressing/)
+    * Double Hashing
     * Bloom filter
 8. Basic graphs
     * Depth-first search

src/algorithms/patternFinding/KMP.java

@@ -17,8 +17,8 @@
  *                 there is no prefix ending before its index, 0, that can be matched with.
  *      Read:          ^   ^ 'B' and 'C' cannot be matched with any prefix which are just 'A' and 'AB' respectively.
  *      Read:                  ^ Can be matched with an earlier 'A'. So we store 1.
- *                             Prefix is the substring from idx 0 to 1 (exclusive).
- *                             Which can also be interpreted as the index of the next character to match against!
+ *                             Prefix is the substring from idx 0 to 1 (exclusive). Note consider prefix from 0-indexed.
+ *                             Realise 1 can also be interpreted as the index of the next character to match against!
  *      Read:                      ^   ^ Similarly, continue matching
  *      Read:                               ^  ^ No matches, so 0
  *      Read:                                      ^   ^   ^   ^   ^   ^ Match with prefix until position 6!

src/dataStructures/queue/MonotonicQueue.java

@@ -0,0 +1,68 @@
+package src.dataStructures.queue;
+
+import java.util.Deque;
+import java.util.ArrayDeque;
+
+/**
+ * Implementation of a non-increasing (decreasing) monotonic queue for certain (but common) use case:
+ * When larger objects pushed to the queue are able to replace and represent smaller objects that come before it.
+ * Callable methods are:
+ * isEmpty()
+ * max()
+ * pop()
+ * push()
+ * @param <T> generic type for objects to be stored or queried
+ *
+ *           index   v   Increasing queue        Decreasing queue
+ * 1       5   [5]                     [5]
+ * 2       3   [3] 3 kick out 5        [5, 3] #3->5
+ * 3       1   [1] 1 kick out 3        [5, 3, 1] #1->3
+ * 4       2   [1, 2] #2->1            [5, 3, 2] 2 kick out 1 #2->3
+ * 5       4   [1, 2, 4] #4->2         [5,4] 4 kick out 2, 3 #4->2
+ */
+
+public class MonotonicQueue<T extends Comparable<T>> {
+  private Deque<T> dq = new ArrayDeque<>(); // or LinkedList
+
+  /**
+   * Checks if queue is empty.
+   * @return boolean
+   */
+  public boolean isEmpty() {
+    return dq.isEmpty();
+  }
+
+  /**
+   * Push an object into the queue and maintain the non-increasing property.
+   * @param obj to be inserted
+   */
+  public void push(T obj) {
+    Integer count = 0;
+    while (!dq.isEmpty() && obj.compareTo(dq.peekLast()) > 0) {
+      dq.pollLast(); // Removes elements that do not conform the non-increasing sequence.
+    }
+    dq.offerLast(obj);
+  }
+
+  /**
+   * Returns the highest value stored in the queue.
+   * @return the first value of the queue.
+   */
+  public T max() {
+    if (isEmpty()) {
+      return null;
+    }
+    return dq.peek();
+  }
+
+  /**
+   * Returns the highest valued object in the queue; i.e the first object;
+   * Removal will only be done all representation of the object has been accounted for.
+   */
+  public T pop() {
+    if (dq.isEmpty()) {
+      return null;
+    }
+    return dq.poll(); // Returns & remove head of deque
+  }
+}

src/dataStructures/stackAndQueue/queue/Queue.java renamed to src/dataStructures/queue/Queue.java

@@ -1,4 +1,4 @@
-package src.dataStructures.stackAndQueue.queue;
+package src.dataStructures.queue;
 
 /**
  * Implementation of a queue structure using LinkedList.

src/dataStructures/queue/README.md

@@ -0,0 +1,68 @@
+# Queue
+
+A queue is a linear data structure that restricts the order in which operations can be performed on its elements.
+
+### Operation Orders
+
+![Queue](https://media.geeksforgeeks.org/wp-content/cdn-uploads/20221213113312/Queue-Data-Structures.png)
+
+*Source: GeeksForGeeks*
+
+Queue follows a FIFO, first in first out order.
+This means the earliest element
+added to the stack is the one operations are conducted on first.
+
+A [stack](../stack/README.md) is a queue with operations conducted in an opposite manner.
+
+## Analysis
+
+As a queue only interacts with either the first or last element regardless during its operations,
+it only needs to keep the pointers of the two element at hand, which is constantly updated as more
+elements are removed / added. This allows stack operations to only incur a *O(1)* time complexity.
+
+## Notes
+
+### Stack vs Queues
+
+Stack and queues only differ in terms of operation order, you should aim to use a stack when
+you want the most recent elements to be operated on.
+Some situations where a stack would work well include build redo / undo systems and backtracking problems.
+
+On the other hand, a queue allows you to operate on elements that enter first. Some situations where
+this would be useful include Breadth First Search algorithms and task / resource allocation systems.
+
+### Arrays vs Linked List
+It is worth noting that queues can be implemented with either a array or with a [linked list](../linkedList/README.md).
+In the context of ordered operations, the lookup is only restricted to the first element.
+
+Hence, there is not much advantage in using a array, which only has a better lookup speed (*O(1)* time complexity)
+to implement a queue. Especially when using a linked list to construct your queue
+would allow you to grow or shrink the queue as you wish.
+
+### Queue Variants
+
+These are some variants of queue that are commonly used.
+
+#### Double Ended Queue (Deque)
+
+![Deque](https://media.geeksforgeeks.org/wp-content/uploads/anod.png)
+
+*Source: GeeksForGeeks*
+
+Deque is a variant of queue where elements can be removed or added from the head and tail of the queue.
+Deque could come in handy when trying to solve sliding window problems.
+
+A deque can be implemented in multiple ways, using doubly linked lists, arrays or two stacks.
+
+#### Monotonic Queue
+
+This is a variant of queue where elements within the queue are either strictly increasing or decreasing.
+Monotonic queues are often implemented with a deque.
+
+Within a increasing monotonic queue, any element that is smaller than the current minimum is removed.
+Within a decreasing monotonic queue, any element that is larger than the current maximum is removed.
+
+It is worth mentioning that the most elements added to the monotonic queue would always be in a 
+increasing / decreasing order,
+hence, we only need to compare down the monotonic queue from the back when adding new elements.
+

src/dataStructures/stack/README.md

@@ -0,0 +1,40 @@
+# Stack
+Stack is a linear data structure that restricts 
+the order in which operations can be performed on its elements.
+
+![Stack data structure](https://cdn.programiz.com/sites/tutorial2program/files/stack.png)
+
+*Source: Programiz*
+
+### Operation Orders
+
+Stack follows a LIFO, last in first out order. 
+This means the most recent element 
+added to the stack is the one operations are conducted on first.
+
+A [queue](../queue/README.md) conducts operations in the opposite order.
+
+## Analysis
+
+As a stack only interacts with the most recent element regardless of operation,
+it keeps the pointer of the most recent element at hand, which is constantly updated as more 
+elements are removed / added. This allows stack operations to only incur a *O(1)* time complexity.
+
+## Notes
+
+### Stack vs Queues
+
+Stack and queues only differ in terms of operation order, you should aim to use a stack when
+you want the most recent elements to be operated on. 
+Some situations where a stack would work well include build redo / undo systems and backtracking problems.
+
+On the other hand, a queue allows you to operate on elements that enter first. Some situations where
+this would be useful include Breadth First Search algorithms and task / resource allocation systems.
+
+### Arrays vs Linked List
+It is worth noting that stacks can be implemented with either a array or with a [linked list](../linkedList/README.md).
+In the context of ordered operations, the lookup is only restricted to the first element.
+
+Hence, there is not much advantage in using a array, which only has a better lookup speed (*O(1)* time complexity) 
+to implement a stack. Especially when using a linked list to construct your stack
+would allow you to grow or shrink the stack as you wish.

src/dataStructures/stackAndQueue/stack/Stack.java renamed to src/dataStructures/stack/Stack.java

@@ -1,4 +1,4 @@
-package src.dataStructures.stackAndQueue.stack;
+package src.dataStructures.stack;
 
 import java.util.List;
 import java.util.ArrayList;