Merge branch 'master' into reverse_stack_improve

Author: Hardvan

DIRECTORY.md

@@ -201,6 +201,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)
@@ -865,6 +866,7 @@
               * [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)
               * [ReverseStackTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/datastructures/stacks/ReverseStackTest.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/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;
+    }
+}

src/test/java/com/thealgorithms/datastructures/lists/RotateSinglyLinkedListsTest.java

@@ -6,67 +6,100 @@
 import org.junit.jupiter.api.Test;
 
 /**
- * Test cases for RotateSinglyLinkedLists
+ * Test cases for RotateSinglyLinkedLists.
  * Author: Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
  */
 public class RotateSinglyLinkedListsTest {
 
+    private final RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
+
+    // Helper method to create a linked list from an array of values
+    private Node createLinkedList(int[] values) {
+        if (values.length == 0) {
+            return null;
+        }
+
+        Node head = new Node(values[0]);
+        Node current = head;
+        for (int i = 1; i < values.length; i++) {
+            current.next = new Node(values[i]);
+            current = current.next;
+        }
+        return head;
+    }
+
+    // Helper method to convert a linked list to a string for easy comparison
+    private String linkedListToString(Node head) {
+        StringBuilder sb = new StringBuilder();
+        Node current = head;
+        while (current != null) {
+            sb.append(current.value);
+            if (current.next != null) {
+                sb.append(" -> ");
+            }
+            current = current.next;
+        }
+        return sb.toString();
+    }
+
     @Test
     public void testRotateRightEmptyList() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
-
-        // Test case: Rotate an empty list
+        // Rotate an empty list
         assertNull(rotator.rotateRight(null, 2));
     }
 
     @Test
     public void testRotateRightSingleNodeList() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
-
-        // Test case: Rotate a list with one element
+        // Rotate a list with a single element
         Node singleNode = new Node(5);
         Node rotatedSingleNode = rotator.rotateRight(singleNode, 3);
-        assertEquals(5, rotatedSingleNode.value);
-        assertNull(rotatedSingleNode.next);
+        assertEquals("5", linkedListToString(rotatedSingleNode));
     }
 
     @Test
     public void testRotateRightMultipleElementsList() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
+        // Rotate a list with multiple elements (rotate by 2)
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 2);
+        assertEquals("4 -> 5 -> 1 -> 2 -> 3", linkedListToString(rotated));
+    }
 
-        // Test case: Rotate a list with multiple elements (Rotate by 2)
-        Node head = new Node(1);
-        head.next = new Node(2);
-        head.next.next = new Node(3);
-        head.next.next.next = new Node(4);
-        head.next.next.next.next = new Node(5);
+    @Test
+    public void testRotateRightFullRotation() {
+        // Rotate by more than the length of the list
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 7);
+        assertEquals("4 -> 5 -> 1 -> 2 -> 3", linkedListToString(rotated));
+    }
 
-        Node rotated1 = rotator.rotateRight(head, 2);
-        assertEquals(4, rotated1.value);
-        assertEquals(5, rotated1.next.value);
-        assertEquals(1, rotated1.next.next.value);
-        assertEquals(2, rotated1.next.next.next.value);
-        assertEquals(3, rotated1.next.next.next.next.value);
-        assertNull(rotated1.next.next.next.next.next);
+    @Test
+    public void testRotateRightZeroRotation() {
+        // Rotate a list by k = 0 (no rotation)
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 0);
+        assertEquals("1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
     }
 
     @Test
-    public void testRotateRightFullRotation() {
-        RotateSinglyLinkedLists rotator = new RotateSinglyLinkedLists();
+    public void testRotateRightByListLength() {
+        // Rotate a list by k equal to list length (no change)
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 5);
+        assertEquals("1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
+    }
 
-        // Test case: Rotate a list with multiple elements (Full rotation)
-        Node head = new Node(1);
-        head.next = new Node(2);
-        head.next.next = new Node(3);
-        head.next.next.next = new Node(4);
-        head.next.next.next.next = new Node(5);
+    @Test
+    public void testRotateRightByMultipleOfListLength() {
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5});
+        Node rotated = rotator.rotateRight(head, 10); // k = 2 * list length
+        assertEquals("1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
+    }
 
-        Node rotated3 = rotator.rotateRight(head, 7);
-        assertEquals(4, rotated3.value);
-        assertEquals(5, rotated3.next.value);
-        assertEquals(1, rotated3.next.next.value);
-        assertEquals(2, rotated3.next.next.next.value);
-        assertEquals(3, rotated3.next.next.next.next.value);
-        assertNull(rotated3.next.next.next.next.next);
+    @Test
+    public void testRotateRightLongerList() {
+        // Rotate a longer list by a smaller k
+        Node head = createLinkedList(new int[] {1, 2, 3, 4, 5, 6, 7, 8, 9});
+        Node rotated = rotator.rotateRight(head, 4);
+        assertEquals("6 -> 7 -> 8 -> 9 -> 1 -> 2 -> 3 -> 4 -> 5", linkedListToString(rotated));
     }
 }

src/test/java/com/thealgorithms/datastructures/queues/TokenBucketTest.java

@@ -0,0 +1,90 @@
+package com.thealgorithms.datastructures.queues;
+
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+public class TokenBucketTest {
+
+    @Test
+    public void testRateLimiter() throws InterruptedException {
+        TokenBucket bucket = new TokenBucket(5, 1);
+        for (int i = 0; i < 5; i++) {
+            assertTrue(bucket.allowRequest());
+        }
+        assertFalse(bucket.allowRequest());
+        Thread.sleep(1000);
+        assertTrue(bucket.allowRequest());
+    }
+
+    @Test
+    public void testRateLimiterWithExceedingRequests() throws InterruptedException {
+        TokenBucket bucket = new TokenBucket(3, 1);
+
+        for (int i = 0; i < 3; i++) {
+            assertTrue(bucket.allowRequest());
+        }
+        assertFalse(bucket.allowRequest());
+
+        Thread.sleep(1000);
+        assertTrue(bucket.allowRequest());
+        assertFalse(bucket.allowRequest());
+    }
+
+    @Test
+    public void testRateLimiterMultipleRefills() throws InterruptedException {
+        TokenBucket bucket = new TokenBucket(2, 1);
+
+        assertTrue(bucket.allowRequest());
+        assertTrue(bucket.allowRequest());
+        assertFalse(bucket.allowRequest());
+
+        Thread.sleep(1000);
+        assertTrue(bucket.allowRequest());
+
+        Thread.sleep(1000);
+        assertTrue(bucket.allowRequest());
+        assertFalse(bucket.allowRequest());
+    }
+
+    @Test
+    public void testRateLimiterEmptyBucket() {
+        TokenBucket bucket = new TokenBucket(0, 1);
+
+        assertFalse(bucket.allowRequest());
+    }
+
+    @Test
+    public void testRateLimiterWithHighRefillRate() throws InterruptedException {
+        TokenBucket bucket = new TokenBucket(5, 10);
+
+        for (int i = 0; i < 5; i++) {
+            assertTrue(bucket.allowRequest());
+        }
+
+        assertFalse(bucket.allowRequest());
+
+        Thread.sleep(1000);
+
+        for (int i = 0; i < 5; i++) {
+            assertTrue(bucket.allowRequest());
+        }
+    }
+
+    @Test
+    public void testRateLimiterWithSlowRequests() throws InterruptedException {
+        TokenBucket bucket = new TokenBucket(5, 1);
+
+        for (int i = 0; i < 5; i++) {
+            assertTrue(bucket.allowRequest());
+        }
+
+        Thread.sleep(1000);
+        assertTrue(bucket.allowRequest());
+
+        Thread.sleep(2000);
+        assertTrue(bucket.allowRequest());
+        assertTrue(bucket.allowRequest());
+    }
+}