From 343dfc91fcc2ddfbfec0cadf702e913c31aa73d3 Mon Sep 17 00:00:00 2001
From: herley <herley.shaori@gmail.com>
Date: Fri, 3 Jul 2026 22:26:32 +0700
Subject: [PATCH] docs: correct stale WiggleSort Javadoc about undetected
 inputs

The class Javadoc claimed [1, 2, 2] slips through undetected, but the
odd-array median guard added later in wiggleSort() already catches
exactly that case and throws IllegalArgumentException. Update the
Javadoc to describe the current behavior and add regression tests
asserting that [1, 2, 2] and arrays with too many duplicates throw
instead of returning a wrongly ordered result.

Fixes TheAlgorithms/Java#7507
---
 .../com/thealgorithms/sorts/WiggleSort.java   |  6 +++---
 .../thealgorithms/sorts/WiggleSortTest.java   | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/src/main/java/com/thealgorithms/sorts/WiggleSort.java b/src/main/java/com/thealgorithms/sorts/WiggleSort.java
index c272b820d07a..0349971d1c95 100644
--- a/src/main/java/com/thealgorithms/sorts/WiggleSort.java
+++ b/src/main/java/com/thealgorithms/sorts/WiggleSort.java
@@ -11,9 +11,9 @@
  * https://cs.stackexchange.com/questions/125372/how-to-wiggle-sort-an-array-in-linear-time-complexity
  * Also have a look at:
  * https://cs.stackexchange.com/questions/125372/how-to-wiggle-sort-an-array-in-linear-time-complexity?noredirect=1&lq=1
- * Not all arrays are wiggle-sortable. This algorithm will find some obviously not wiggle-sortable
- * arrays and throw an error, but there are some exceptions that won't be caught, for example [1, 2,
- * 2].
+ * Not all arrays are wiggle-sortable. This algorithm detects non-wiggle-sortable inputs — for
+ * example [1, 2, 2], or arrays where more than half the values are equal — and throws an
+ * IllegalArgumentException instead of returning a wrongly ordered result.
  */
 public class WiggleSort implements SortAlgorithm {
 
diff --git a/src/test/java/com/thealgorithms/sorts/WiggleSortTest.java b/src/test/java/com/thealgorithms/sorts/WiggleSortTest.java
index c5d57d63cf38..0d8b6acf9043 100644
--- a/src/test/java/com/thealgorithms/sorts/WiggleSortTest.java
+++ b/src/test/java/com/thealgorithms/sorts/WiggleSortTest.java
@@ -1,6 +1,7 @@
 package com.thealgorithms.sorts;
 
 import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import java.util.Arrays;
 import org.junit.jupiter.api.Test;
@@ -70,4 +71,22 @@ void wiggleTestStrings() {
         wiggleSort.sort(values);
         assertArrayEquals(values, result);
     }
+
+    @Test
+    void wiggleTestNonWiggleSortableOddArrayThrows() {
+        // [1, 2, 2] is not wiggle-sortable: the median 2 appears ceil(3 / 2) = 2 times
+        // but is not the smallest value, so sorting must fail instead of returning
+        // a wrongly ordered array
+        WiggleSort wiggleSort = new WiggleSort();
+        Integer[] values = {1, 2, 2};
+        assertThrows(IllegalArgumentException.class, () -> wiggleSort.sort(values));
+    }
+
+    @Test
+    void wiggleTestTooManyDuplicatesThrows() {
+        // more than half of the values are the same, which can never be wiggle-sorted
+        WiggleSort wiggleSort = new WiggleSort();
+        Integer[] values = {2, 2, 2, 1};
+        assertThrows(IllegalArgumentException.class, () -> wiggleSort.sort(values));
+    }
 }