Add suggested changes

Author: Hardvan

src/main/java/com/thealgorithms/datastructures/buffers/CircularBuffer.java

@@ -6,6 +6,7 @@
  * The {@code CircularBuffer} class implements a generic circular (or ring) buffer.
  * A circular buffer is a fixed-size data structure that operates in a FIFO (First In, First Out) manner.
  * The buffer allows you to overwrite old data when the buffer is full and efficiently use limited memory.
+ * When the buffer is full, adding a new item will overwrite the oldest data.
  *
  * @param <Item> The type of elements stored in the circular buffer.
  */
@@ -19,8 +20,12 @@ public class CircularBuffer<Item> {
      * Constructor to initialize the circular buffer with a specified size.
      *
      * @param size The size of the circular buffer.
+     * @throws IllegalArgumentException if the size is zero or negative.
      */
     public CircularBuffer(int size) {
+        if (size <= 0) {
+            throw new IllegalArgumentException("Buffer size must be positive");
+        }
         // noinspection unchecked
         this.buffer = (Item[]) new Object[size];
         this.putPointer = new CircularPointer(0, size);
@@ -29,6 +34,7 @@ public CircularBuffer(int size) {
 
     /**
      * Checks if the circular buffer is empty.
+     * This method is based on the current size of the buffer.
      *
      * @return {@code true} if the buffer is empty, {@code false} otherwise.
      */
@@ -38,6 +44,7 @@ public boolean isEmpty() {
 
     /**
      * Checks if the circular buffer is full.
+     * The buffer is considered full when its size equals its capacity.
      *
      * @return {@code true} if the buffer is full, {@code false} otherwise.
      */
@@ -47,6 +54,7 @@ public boolean isFull() {
 
     /**
      * Retrieves and removes the item at the front of the buffer (FIFO).
+     * This operation will move the {@code getPointer} forward.
      *
      * @return The item at the front of the buffer, or {@code null} if the buffer is empty.
      */
@@ -62,23 +70,37 @@ public Item get() {
 
     /**
      * Adds an item to the end of the buffer (FIFO).
+     * If the buffer is full, this operation will overwrite the oldest data.
      *
      * @param item The item to be added.
-     * @return {@code true} if the item was successfully added, or {@code false} if the buffer is full.
+     * @throws IllegalArgumentException if the item is null.
+     * @return {@code true} if the item was successfully added, {@code false} if the buffer was full and the item overwrote existing data.
      */
     public boolean put(Item item) {
+        if (item == null) {
+            throw new IllegalArgumentException("Null items are not allowed");
+        }
+
+        boolean wasEmpty = isEmpty();
         if (isFull()) {
-            return false;
+            getPointer.getAndIncrement(); // Move get pointer to discard oldest item
+        } else {
+            size.incrementAndGet();
         }
 
         buffer[putPointer.getAndIncrement()] = item;
-        size.incrementAndGet();
-        return true;
+        return wasEmpty;
     }
 
     /**
      * The {@code CircularPointer} class is a helper class used to track the current index (pointer)
-     * in the circular buffer. It automatically wraps around when reaching the maximum index.
+     * in the circular buffer.
+     * The max value represents the capacity of the buffer.
+     * The `CircularPointer` class ensures that the pointer automatically wraps around to 0
+     * when it reaches the maximum index.
+     * This is achieved in the `getAndIncrement` method, where the pointer
+     * is incremented and then taken modulo the maximum value (`max`).
+     * This operation ensures that the pointer always stays within the bounds of the buffer.
      */
     private static class CircularPointer {
         private int pointer;
@@ -96,16 +118,14 @@ private static class CircularPointer {
         }
 
         /**
-         * Increments the pointer by 1 and wraps it around to 0 if it exceeds the maximum value.
+         * Increments the pointer by 1 and wraps it around to 0 if it reaches the maximum value.
+         * This ensures the pointer always stays within the buffer's bounds.
          *
          * @return The current pointer value before incrementing.
          */
         public int getAndIncrement() {
-            if (pointer == max) {
-                pointer = 0;
-            }
             int tmp = pointer;
-            pointer++;
+            pointer = (pointer + 1) % max;
             return tmp;
         }
     }