From b14db816bdf73db25812f91b507d0c88160fdadf Mon Sep 17 00:00:00 2001
From: Rashi Dashore <119104356+rashi07dashore@users.noreply.github.com>
Date: Wed, 30 Oct 2024 02:00:22 +0530
Subject: [PATCH] Add shuffle array (#6026)

---
 .../com/thealgorithms/misc/ShuffleArray.java  | 38 +++++++++
 .../thealgorithms/misc/ShuffleArrayTest.java  | 84 +++++++++++++++++++
 2 files changed, 122 insertions(+)
 create mode 100644 src/main/java/com/thealgorithms/misc/ShuffleArray.java
 create mode 100644 src/test/java/com/thealgorithms/misc/ShuffleArrayTest.java

diff --git a/src/main/java/com/thealgorithms/misc/ShuffleArray.java b/src/main/java/com/thealgorithms/misc/ShuffleArray.java
new file mode 100644
index 000000000..65d38adfc
--- /dev/null
+++ b/src/main/java/com/thealgorithms/misc/ShuffleArray.java
@@ -0,0 +1,38 @@
+package com.thealgorithms.misc;
+
+import java.util.Random;
+
+/**
+ * The Fisher-Yates (Knuth) Shuffle algorithm randomly permutes an array's
+ * elements, ensuring each permutation is equally likely.
+ *
+ * <p>
+ * Worst-case performance O(n)
+ * Best-case performance O(n)
+ * Average performance O(n)
+ * Worst-case space complexity O(1)
+ *
+ * This class provides a static method to shuffle an array in place.
+ *
+ * @author Rashi Dashore (https://github.com/rashi07dashore)
+ */
+public final class ShuffleArray {
+    // Prevent instantiation
+    private ShuffleArray() {
+    }
+
+    /**
+     * This method shuffles an array using the Fisher-Yates algorithm.
+     *
+     * @param arr is the input array to be shuffled
+     */
+    public static void shuffle(int[] arr) {
+        Random random = new Random();
+        for (int i = arr.length - 1; i > 0; i--) {
+            int j = random.nextInt(i + 1);
+            int temp = arr[i];
+            arr[i] = arr[j];
+            arr[j] = temp;
+        }
+    }
+}
diff --git a/src/test/java/com/thealgorithms/misc/ShuffleArrayTest.java b/src/test/java/com/thealgorithms/misc/ShuffleArrayTest.java
new file mode 100644
index 000000000..915b83e37
--- /dev/null
+++ b/src/test/java/com/thealgorithms/misc/ShuffleArrayTest.java
@@ -0,0 +1,84 @@
+package com.thealgorithms.misc;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+public class ShuffleArrayTest {
+
+    @Test
+    void testShuffleBasic() {
+        int[] arr = {1, 2, 3, 4, 5};
+        int[] originalArr = arr.clone(); // Clone original array for comparison
+        ShuffleArray.shuffle(arr);
+
+        // Check that the shuffled array is not the same as the original
+        assertNotEquals(originalArr, arr);
+    }
+
+    @Test
+    void testShuffleSingleElement() {
+        int[] arr = {1};
+        int[] originalArr = arr.clone();
+        ShuffleArray.shuffle(arr);
+
+        // Check that the shuffled array is the same as the original
+        assertArrayEquals(originalArr, arr);
+    }
+
+    @Test
+    void testShuffleTwoElements() {
+        int[] arr = {1, 2};
+        int[] originalArr = arr.clone();
+        ShuffleArray.shuffle(arr);
+
+        // Check that the shuffled array is not the same as the original
+        assertNotEquals(originalArr, arr);
+        // Check that the shuffled array still contains the same elements
+        assertTrue(arr[0] == 1 || arr[0] == 2);
+        assertTrue(arr[1] == 1 || arr[1] == 2);
+    }
+
+    @Test
+    void testShuffleEmptyArray() {
+        int[] arr = {};
+        int[] originalArr = arr.clone();
+        ShuffleArray.shuffle(arr);
+
+        // Check that the shuffled array is the same as the original (still empty)
+        assertArrayEquals(originalArr, arr);
+    }
+
+    @Test
+    void testShuffleLargeArray() {
+        int[] arr = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10};
+        int[] originalArr = arr.clone();
+        ShuffleArray.shuffle(arr);
+
+        // Check that the shuffled array is not the same as the original
+        assertNotEquals(originalArr, arr);
+    }
+
+    @Test
+    void testShuffleRetainsElements() {
+        int[] arr = {1, 2, 3, 4, 5};
+        ShuffleArray.shuffle(arr);
+
+        // Check that the shuffled array contains the same elements
+        assertTrue(arr.length == 5);
+        for (int i = 1; i <= 5; i++) {
+            assertTrue(contains(arr, i));
+        }
+    }
+
+    private boolean contains(int[] arr, int value) {
+        for (int num : arr) {
+            if (num == value) {
+                return true;
+            }
+        }
+        return false;
+    }
+}