Merge branch 'master' into master

Author: khwaishchawla

src/main/java/com/thealgorithms/datastructures/caches/LFUCache.java

@@ -6,16 +6,21 @@
 /**
  * The {@code LFUCache} class implements a Least Frequently Used (LFU) cache.
  * An LFU cache evicts the least frequently used item when the cache reaches its capacity.
- * It keeps track of how many times each item is used and maintains a doubly linked list
- * for efficient addition and removal of items based on their frequency of use.
+ * It maintains a mapping of keys to nodes, where each node contains the key, its associated value,
+ * and a frequency count that tracks how many times the item has been accessed. A doubly linked list
+ * is used to efficiently manage the ordering of items based on their usage frequency.
  *
- * @param <K> The type of keys maintained by this cache.
- * @param <V> The type of mapped values.
+ * <p>This implementation is designed to provide O(1) time complexity for both the {@code get} and
+ * {@code put} operations, which is achieved through the use of a hashmap for quick access and a
+ * doubly linked list for maintaining the order of item frequencies.</p>
  *
  * <p>
  * Reference: <a href="https://en.wikipedia.org/wiki/Least_frequently_used">LFU Cache - Wikipedia</a>
  * </p>
  *
+ * @param <K> The type of keys maintained by this cache.
+ * @param <V> The type of mapped values.
+ *
  * @author Akshay Dubey (https://github.com/itsAkshayDubey)
  */
 public class LFUCache<K, V> {
@@ -75,7 +80,7 @@ public LFUCache(int capacity) {
 
     /**
      * Retrieves the value associated with the given key from the cache.
-     * If the key exists, the node's frequency is increased and the node is repositioned
+     * If the key exists, the node's frequency is incremented, and the node is repositioned
      * in the linked list based on its updated frequency.
      *
      * @param key The key whose associated value is to be returned.

src/main/java/com/thealgorithms/datastructures/caches/LRUCache.java

@@ -4,15 +4,40 @@
 import java.util.Map;
 
 /**
- * Least recently used (LRU)
- * <p>
- * Discards the least recently used items first. This algorithm requires keeping
- * track of what was used when, which is expensive if one wants to make sure the
- * algorithm always discards the least recently used item.
- * https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)
+ * A Least Recently Used (LRU) Cache implementation.
  *
- * @param <K> key type
- * @param <V> value type
+ * <p>An LRU cache is a fixed-size cache that maintains items in order of use. When the cache reaches
+ * its capacity and a new item needs to be added, it removes the least recently used item first.
+ * This implementation provides O(1) time complexity for both get and put operations.</p>
+ *
+ * <p>Features:</p>
+ * <ul>
+ *   <li>Fixed-size cache with configurable capacity</li>
+ *   <li>Constant time O(1) operations for get and put</li>
+ *   <li>Thread-unsafe - should be externally synchronized if used in concurrent environments</li>
+ *   <li>Supports null values but not null keys</li>
+ * </ul>
+ *
+ * <p>Implementation Details:</p>
+ * <ul>
+ *   <li>Uses a HashMap for O(1) key-value lookups</li>
+ *   <li>Maintains a doubly-linked list for tracking access order</li>
+ *   <li>The head of the list contains the least recently used item</li>
+ *   <li>The tail of the list contains the most recently used item</li>
+ * </ul>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * LRUCache<String, Integer> cache = new LRUCache<>(3); // Create cache with capacity 3
+ * cache.put("A", 1); // Cache: A=1
+ * cache.put("B", 2); // Cache: A=1, B=2
+ * cache.put("C", 3); // Cache: A=1, B=2, C=3
+ * cache.get("A");    // Cache: B=2, C=3, A=1 (A moved to end)
+ * cache.put("D", 4); // Cache: C=3, A=1, D=4 (B evicted)
+ * </pre>
+ *
+ * @param <K> the type of keys maintained by this cache
+ * @param <V> the type of mapped values
  */
 public class LRUCache<K, V> {
 
@@ -30,6 +55,11 @@ public LRUCache(int cap) {
         setCapacity(cap);
     }
 
+    /**
+     * Returns the current capacity of the cache.
+     *
+     * @param newCapacity the new capacity of the cache
+     */
     private void setCapacity(int newCapacity) {
         checkCapacity(newCapacity);
         for (int i = data.size(); i > newCapacity; i--) {
@@ -39,6 +69,11 @@ private void setCapacity(int newCapacity) {
         this.cap = newCapacity;
     }
 
+    /**
+     * Evicts the least recently used item from the cache.
+     *
+     * @return the evicted entry
+     */
     private Entry<K, V> evict() {
         if (head == null) {
             throw new RuntimeException("cache cannot be empty!");
@@ -50,12 +85,25 @@ private Entry<K, V> evict() {
         return evicted;
     }
 
+    /**
+     * Checks if the capacity is valid.
+     *
+     * @param capacity the capacity to check
+     */
     private void checkCapacity(int capacity) {
         if (capacity <= 0) {
             throw new RuntimeException("capacity must greater than 0!");
         }
     }
 
+    /**
+     * Returns the value to which the specified key is mapped, or null if this cache contains no
+     * mapping for the key.
+     *
+     * @param key the key whose associated value is to be returned
+     * @return the value to which the specified key is mapped, or null if this cache contains no
+     * mapping for the key
+     */
     public V get(K key) {
         if (!data.containsKey(key)) {
             return null;
@@ -65,6 +113,11 @@ public V get(K key) {
         return entry.getValue();
     }
 
+    /**
+     * Moves the specified entry to the end of the list.
+     *
+     * @param entry the entry to move
+     */
     private void moveNodeToLast(Entry<K, V> entry) {
         if (tail == entry) {
             return;
@@ -86,6 +139,12 @@ private void moveNodeToLast(Entry<K, V> entry) {
         tail = entry;
     }
 
+    /**
+     * Associates the specified value with the specified key in this cache.
+     *
+     * @param key the key with which the specified value is to be associated
+     * @param value the value to be associated with the specified key
+     */
     public void put(K key, V value) {
         if (data.containsKey(key)) {
             final Entry<K, V> existingEntry = data.get(key);
@@ -107,6 +166,11 @@ public void put(K key, V value) {
         data.put(key, newEntry);
     }
 
+    /**
+     * Adds a new entry to the end of the list.
+     *
+     * @param newEntry the entry to add
+     */
     private void addNewEntry(Entry<K, V> newEntry) {
         if (data.isEmpty()) {
             head = newEntry;

src/test/java/com/thealgorithms/datastructures/caches/LFUCacheTest.java

@@ -1,6 +1,8 @@
 package com.thealgorithms.datastructures.caches;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import org.junit.jupiter.api.Test;
 
@@ -22,15 +24,15 @@ void testLFUCacheWithIntegerValueShouldPass() {
         lfuCache.put(6, 60);
 
         // will return null as value with key 2 is now evicted
-        assertEquals(null, lfuCache.get(2));
+        assertNull(lfuCache.get(2));
 
         // should return 60
         assertEquals(60, lfuCache.get(6));
 
         // this operation will remove value with key as 3
         lfuCache.put(7, 70);
 
-        assertEquals(null, lfuCache.get(2));
+        assertNull(lfuCache.get(2));
         assertEquals(70, lfuCache.get(7));
     }
 
@@ -41,7 +43,7 @@ void testLFUCacheWithStringValueShouldPass() {
         lfuCache.put(2, "Beta");
         lfuCache.put(3, "Gamma");
         lfuCache.put(4, "Delta");
-        lfuCache.put(5, "Eplison");
+        lfuCache.put(5, "Epsilon");
 
         // get method call will increase frequency of key 1 by 1
         assertEquals("Alpha", lfuCache.get(1));
@@ -50,33 +52,87 @@ void testLFUCacheWithStringValueShouldPass() {
         lfuCache.put(6, "Digamma");
 
         // will return null as value with key 2 is now evicted
-        assertEquals(null, lfuCache.get(2));
+        assertNull(lfuCache.get(2));
 
         // should return string Digamma
         assertEquals("Digamma", lfuCache.get(6));
 
         // this operation will remove value with key as 3
         lfuCache.put(7, "Zeta");
 
-        assertEquals(null, lfuCache.get(2));
+        assertNull(lfuCache.get(2));
         assertEquals("Zeta", lfuCache.get(7));
     }
 
-    /**
-     * test addNodeWithUpdatedFrequency method
-     * @author yuluo
-     */
     @Test
-    void testAddNodeWithUpdatedFrequency() {
+    void testUpdateValueShouldPreserveFrequency() {
         LFUCache<Integer, String> lfuCache = new LFUCache<>(3);
-        lfuCache.put(1, "beijing");
-        lfuCache.put(2, "shanghai");
-        lfuCache.put(3, "gansu");
+        lfuCache.put(1, "A");
+        lfuCache.put(2, "B");
+        lfuCache.put(3, "C");
 
-        assertEquals("beijing", lfuCache.get(1));
+        assertEquals("A", lfuCache.get(1)); // Accessing key 1
+        lfuCache.put(4, "D"); // This should evict key 2
 
-        lfuCache.put(1, "shanxi");
+        assertNull(lfuCache.get(2)); // Key 2 should be evicted
+        assertEquals("C", lfuCache.get(3)); // Key 3 should still exist
+        assertEquals("A", lfuCache.get(1)); // Key 1 should still exist
 
-        assertEquals("shanxi", lfuCache.get(1));
+        lfuCache.put(1, "Updated A"); // Update the value of key 1
+        assertEquals("Updated A", lfuCache.get(1)); // Check if the update was successful
+    }
+
+    @Test
+    void testEvictionPolicyWhenFull() {
+        LFUCache<Integer, String> lfuCache = new LFUCache<>(2);
+        lfuCache.put(1, "One");
+        lfuCache.put(2, "Two");
+
+        assertEquals("One", lfuCache.get(1)); // Access key 1
+        lfuCache.put(3, "Three"); // This should evict key 2 (least frequently used)
+
+        assertNull(lfuCache.get(2)); // Key 2 should be evicted
+        assertEquals("One", lfuCache.get(1)); // Key 1 should still exist
+        assertEquals("Three", lfuCache.get(3)); // Check if key 3 exists
+    }
+
+    @Test
+    void testGetFromEmptyCacheShouldReturnNull() {
+        LFUCache<Integer, String> lfuCache = new LFUCache<>(3);
+        assertNull(lfuCache.get(1)); // Should return null as the cache is empty
+    }
+
+    @Test
+    void testPutNullValueShouldStoreNull() {
+        LFUCache<Integer, String> lfuCache = new LFUCache<>(3);
+        lfuCache.put(1, null); // Store a null value
+
+        assertNull(lfuCache.get(1)); // Should return null
+    }
+
+    @Test
+    void testInvalidCacheCapacityShouldThrowException() {
+        assertThrows(IllegalArgumentException.class, () -> new LFUCache<>(0));
+        assertThrows(IllegalArgumentException.class, () -> new LFUCache<>(-1));
+    }
+
+    @Test
+    void testMultipleAccessPatterns() {
+        LFUCache<Integer, String> lfuCache = new LFUCache<>(5);
+        lfuCache.put(1, "A");
+        lfuCache.put(2, "B");
+        lfuCache.put(3, "C");
+        lfuCache.put(4, "D");
+
+        assertEquals("A", lfuCache.get(1)); // Access 1
+        lfuCache.put(5, "E"); // Should not evict anything yet
+        lfuCache.put(6, "F"); // Evict B
+
+        assertNull(lfuCache.get(2)); // B should be evicted
+        assertEquals("C", lfuCache.get(3)); // C should still exist
+        assertEquals("D", lfuCache.get(4)); // D should still exist
+        assertEquals("A", lfuCache.get(1)); // A should still exist
+        assertEquals("E", lfuCache.get(5)); // E should exist
+        assertEquals("F", lfuCache.get(6)); // F should exist
     }
 }