Merge branch 'master' into merge_k_sorted_new_algo

Author: Hardvan

DIRECTORY.md

@@ -202,6 +202,7 @@
               * [PriorityQueues](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/datastructures/queues/PriorityQueues.java)
               * [Queue](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/datastructures/queues/Queue.java)
               * [QueueByTwoStacks](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/datastructures/queues/QueueByTwoStacks.java)
+              * [TokenBucket](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/datastructures/queues/TokenBucket.java)
             * stacks
               * [NodeStack](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/datastructures/stacks/NodeStack.java)
               * [ReverseStack](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/datastructures/stacks/ReverseStack.java)
@@ -867,7 +868,9 @@
               * [PriorityQueuesTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/queues/PriorityQueuesTest.java)
               * [QueueByTwoStacksTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/queues/QueueByTwoStacksTest.java)
               * [QueueTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/queues/QueueTest.java)
+              * [TokenBucketTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/queues/TokenBucketTest.java)
             * stacks
+              * [NodeStackTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/stacks/NodeStackTest.java)
               * [StackArrayListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/stacks/StackArrayListTest.java)
               * [StackArrayTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/stacks/StackArrayTest.java)
               * [StackOfLinkedListTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/stacks/StackOfLinkedListTest.java)

src/main/java/com/thealgorithms/datastructures/lists/RotateSinglyLinkedLists.java

@@ -1,11 +1,43 @@
 package com.thealgorithms.datastructures.lists;
 
 /**
- * Rotate a list
- * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
+ * The RotateSinglyLinkedLists class provides a method to rotate a singly linked list
+ * to the right by a specified number of positions.
+ * <p>
+ * In a right rotation by `k` steps, each node in the list moves `k` positions to the right.
+ * Nodes that are rotated off the end of the list are placed back at the beginning.
+ * </p>
+ * <p>
+ * Example:
+ * Given linked list: 1 -> 2 -> 3 -> 4 -> 5 and k = 2, the output will be:
+ * 4 -> 5 -> 1 -> 2 -> 3.
+ * </p>
+ * <p>
+ * Edge Cases:
+ * <ul>
+ *   <li>If the list is empty, returns null.</li>
+ *   <li>If `k` is 0 or a multiple of the list length, the list remains unchanged.</li>
+ * </ul>
+ * </p>
+ * <p>
+ * Complexity:
+ * <ul>
+ *   <li>Time Complexity: O(n), where n is the number of nodes in the linked list.</li>
+ *   <li>Space Complexity: O(1), as we only use a constant amount of additional space.</li>
+ * </ul>
+ * </p>
+ *
+ * Author: Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
-
 public class RotateSinglyLinkedLists {
+
+    /**
+     * Rotates a singly linked list to the right by `k` positions.
+     *
+     * @param head The head node of the singly linked list.
+     * @param k The number of positions to rotate the list to the right.
+     * @return The head of the rotated linked list.
+     */
     public Node rotateRight(Node head, int k) {
         if (head == null || head.next == null || k == 0) {
             return head;

src/main/java/com/thealgorithms/datastructures/queues/GenericArrayListQueue.java

@@ -4,43 +4,46 @@
 import java.util.List;
 
 /**
- * This class implements a GenericArrayListQueue.
+ * This class implements a GenericArrayListQueue, a queue data structure that
+ * holds elements of any type specified at runtime, allowing flexibility in the type
+ * of elements it stores.
  *
- * A GenericArrayListQueue data structure functions the same as any
- * specific-typed queue. The GenericArrayListQueue holds elements of types
- * to-be-specified at runtime. The elements that are added first are the first
- * to be removed (FIFO). New elements are added to the back/rear of the queue.
+ * <p>The GenericArrayListQueue operates on a First-In-First-Out (FIFO) basis, where
+ * elements added first are the first to be removed. New elements are added to the back
+ * (or rear) of the queue, while removal of elements occurs from the front.
+ *
+ * @param <T> The type of elements held in this queue.
  */
 public class GenericArrayListQueue<T> {
 
     /**
-     * The generic List for the queue. T is the generic element type.
+     * A list that stores the queue's elements in insertion order.
      */
     private final List<T> elementList = new ArrayList<>();
 
     /**
      * Checks if the queue is empty.
      *
-     * @return True if the queue is empty, false otherwise.
+     * @return {@code true} if the queue has no elements; {@code false} otherwise.
      */
-    private boolean isEmpty() {
+    public boolean isEmpty() {
         return elementList.isEmpty();
     }
 
     /**
-     * Returns the element at the front of the queue without removing it.
+     * Retrieves, but does not remove, the element at the front of the queue.
      *
-     * @return The element at the front of the queue, or null if the queue is empty.
+     * @return The element at the front of the queue, or {@code null} if the queue is empty.
      */
     public T peek() {
         return isEmpty() ? null : elementList.getFirst();
     }
 
     /**
-     * Inserts an element of type T to the back of the queue.
+     * Inserts an element at the back of the queue.
      *
-     * @param element the element to be added to the queue.
-     * @return True if the element was added successfully.
+     * @param element The element to be added to the queue.
+     * @return {@code true} if the element was successfully added.
      */
     public boolean add(T element) {
         return elementList.add(element);
@@ -49,7 +52,7 @@ public boolean add(T element) {
     /**
      * Retrieves and removes the element at the front of the queue.
      *
-     * @return The element removed from the front of the queue, or null if the queue is empty.
+     * @return The element removed from the front of the queue, or {@code null} if the queue is empty.
      */
     public T poll() {
         return isEmpty() ? null : elementList.removeFirst();

src/main/java/com/thealgorithms/datastructures/queues/TokenBucket.java

@@ -0,0 +1,61 @@
+package com.thealgorithms.datastructures.queues;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * TokenBucket implements a token bucket rate limiter algorithm.
+ * This class is used to control the rate of requests in a distributed system.
+ * It allows a certain number of requests (tokens) to be processed in a time frame,
+ * based on the defined refill rate.
+ *
+ * Applications: Computer networks, API rate limiting, distributed systems, etc.
+ *
+ * @author Hardvan
+ */
+public final class TokenBucket {
+    private final int maxTokens;
+    private final int refillRate; // tokens per second
+    private int tokens;
+    private long lastRefill; // Timestamp in nanoseconds
+
+    /**
+     * Constructs a TokenBucket instance.
+     *
+     * @param maxTokens  Maximum number of tokens the bucket can hold.
+     * @param refillRate The rate at which tokens are refilled (tokens per second).
+     */
+    public TokenBucket(int maxTokens, int refillRate) {
+        this.maxTokens = maxTokens;
+        this.refillRate = refillRate;
+        this.tokens = maxTokens;
+        this.lastRefill = System.nanoTime();
+    }
+
+    /**
+     * Attempts to allow a request based on the available tokens.
+     * If a token is available, it decrements the token count and allows the request.
+     * Otherwise, the request is denied.
+     *
+     * @return true if the request is allowed, false if the request is denied.
+     */
+    public synchronized boolean allowRequest() {
+        refillTokens();
+        if (tokens > 0) {
+            tokens--;
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Refills the tokens based on the time elapsed since the last refill.
+     * The number of tokens to be added is calculated based on the elapsed time
+     * and the refill rate, ensuring the total does not exceed maxTokens.
+     */
+    private void refillTokens() {
+        long now = System.nanoTime();
+        long tokensToAdd = (now - lastRefill) / TimeUnit.SECONDS.toNanos(1) * refillRate;
+        tokens = Math.min(maxTokens, tokens + (int) tokensToAdd);
+        lastRefill = now;
+    }
+}