docs: clarify hash() limitations in BucketSort; add tests demonstrating

distribution behavior

Author: Leogricci

src/main/java/com/thealgorithms/sorts/BucketSort.java

@@ -95,6 +95,22 @@ private <T extends Comparable<T>> T[] concatenateBuckets(Iterable<List<T>> bucke
      * This is done by "normalizing" the element within the range of the array's minimum (min) and maximum (max) values,
      * and then mapping this normalized value to a specific bucket index.
      *
+     *<p><b>Important limitations:</b>
+     *<ul>
+	 *   <li>This method uses {@code compareTo} as if it provided a numeric difference. 
+	 *   For numeric types, {@code compareTo} only reports order (−1, 0, 1), not the actual distance. 
+	 *   This often collapses distribution into one or two buckets.</li>
+	 *   <li>For non-numeric {@code Comparable} types (for example {@code String}), bucket indices depend on lexicographic 
+	 *   code-point differences, which are not a proportional measure of spacing. Distribution is therefore arbitrary and uneven.</li>
+	 *   <li>If {@code min.equals(max)}, the computed "range" is 0. Then {@code element.compareTo(min) / 0} 
+	 *   yields {@code NaN}, which Java coerces to 0 when cast to {@code int}. 
+	 *   Practically, all elements collapse into bucket 0 in this case.</li>
+	 * </ul>
+	 *
+	 * <p>Despite these limitations, the sort remains correct because each bucket is sorted internally and concatenated. 
+	 * This method should be regarded as a simplified demonstration rather than a
+	 * general-purpose bucketing strategy for arbitrary {@code Comparable<T>} values.</p>
+     *
      * @param element the element of the array
      * @param min the minimum value in the array
      * @param max the maximum value in the array

src/test/java/com/thealgorithms/sorts/BucketSortHashBehaviorTest.java

@@ -0,0 +1,73 @@
+package com.thealgorithms.sorts;
+
+import static org.junit.jupiter.api.Assertions.assertArrayEquals;
+
+import java.util.Arrays;
+import java.util.List;
+import org.junit.jupiter.api.Test;
+
+public class BucketSortHashBehaviorTest {
+
+    private static <T extends Comparable<T>> int pseudoHash(final T element, final T min, final T max, final int numberOfBuckets) {
+        //Reproduces the production hash() logic
+        double range = max.compareTo(min);
+        double normalizedValue = element.compareTo(min) / range; // -1/0/1 divided by -1/0/1
+        return (int) (normalizedValue * (numberOfBuckets - 1));
+    }
+
+    @Test //Test case when all numbers are equal
+    void sort_stillCorrect_whenAllEqual() {
+        Integer[] arr = {1, 1, 1, 1, 1};
+        Integer[] expected = arr.clone();
+
+        new BucketSort().sort(arr);
+        assertArrayEquals(expected, arr);
+
+        //Observe bucket mapping (all collapse to index 0)
+        Integer min = 1, max = 1;
+        int numberOfBuckets = Math.max(arr.length / 10, 1); // same as BUCKET_DIVISOR rule
+        int idx = pseudoHash(1, min, max, numberOfBuckets);
+        //idx will be 0 because NaN cast to int -> 0 in Java
+        System.out.println("All-equal case -> bucket index: " + idx);
+    }
+
+    @Test //Test case with non-equal integers
+    void sort_stillCorrect_nonEqualIntegers() {
+        Integer[] arr = {20, 40, 30, 10};
+        Integer[] expected = {10, 20, 30, 40};
+
+        new BucketSort().sort(arr);
+        assertArrayEquals(expected, arr);
+
+        Integer min = Arrays.stream(arr).min(Integer::compareTo).get();
+        Integer max = Arrays.stream(arr).max(Integer::compareTo).get();
+        int numberOfBuckets = Math.max(arr.length / 10, 1); // often 1 here; bump to 4 to demonstrate
+        numberOfBuckets = 4;
+
+        for (Integer x : arr) {
+            int idx = pseudoHash(x, min, max, numberOfBuckets);
+            System.out.println("Value " + x + " -> bucket " + idx);
+        }
+        // Expect only two distinct buckets because compareTo gives -1/0/1
+    }
+
+    @Test //Test case when the Array contains Strings
+    void sort_stillCorrect_whenStrings() {
+        String[] arr = {"apple", "banana", "carrot"};
+        String[] expected = arr.clone();
+
+        new BucketSort().sort(arr);
+        assertArrayEquals(expected, arr);
+
+        String min = Arrays.stream(arr).min(String::compareTo).get();
+        String max = Arrays.stream(arr).max(String::compareTo).get();
+        int numberOfBuckets = 4;
+
+        for (String s : arr) {
+            int idx = pseudoHash(s, min, max, numberOfBuckets);
+            System.out.println("Value \"" + s + "\" -> bucket " + idx);
+        }
+        // Buckets reflect only lexicographic order, not a numeric spacing
+    }
+}
+