Add findDuplicates Method to ListUtils with Comprehensive Test Cases

src/main/java/org/apache/commons/collections4/ListUtils.java

@@ -24,6 +24,7 @@
 import java.util.Iterator;
 import java.util.List;
 import java.util.Objects;
+import java.util.Set;
 
 import org.apache.commons.collections4.bag.HashBag;
 import org.apache.commons.collections4.functors.DefaultEquator;
@@ -173,6 +174,39 @@ public static <E> List<E> fixedSizeList(final List<E> list) {
         return FixedSizeList.fixedSizeList(list);
     }
 
+    /**
+     * Finds and returns a list of duplicate elements in the given list.
+     * <p>
+     * This method uses two sets: one for tracking seen elements and one for
+     * collecting duplicates. It iterates through the list once and collects
+     * duplicates in a result list.
+     * </p>
+     *
+     * @param <E> the type of elements in the list
+     * @param list the list to check for duplicates, must not be null
+     * @return a list of duplicate elements, or an empty list if no duplicates are found
+     * @throws NullPointerException if the list is null
+     */
+    public static <E> List<E> findDuplicates(final List<E> list) {
+        if (list == null) {
+            throw new NullPointerException("The input list must not be null.");
+        }
+
+        Set<E> seen = new HashSet<>();
+        Set<E> duplicates = new HashSet<>();
+        List<E> result = new ArrayList<>();
+
+        for (E element : list) {
+            if (!seen.add(element)) {
+                if (duplicates.add(element)) {
+                    result.add(element);
+                }
+            }
+        }
+
+        return result;
+    }
+
     /**
      * Gets the first element of a list.
      * <p>

src/test/java/org/apache/commons/collections4/ListUtilsTest.java

@@ -102,6 +102,54 @@ public void testEquals() {
         assertFalse(ListUtils.isEqualList(list1, list2));
     }
 
+    @Test
+    public void testFindDuplicatesWithDuplicates() {
+        List<Integer> input = Arrays.asList(1, 2, 3, 2, 4, 5, 3);
+        List<Integer> expected = Arrays.asList(2, 3);
+        List<Integer> actual = ListUtils.findDuplicates(input);
+        assertEquals(expected, actual, "The list should contain only the duplicate elements.");
+    }
+
+    @Test
+    public void testFindDuplicatesNoDuplicates() {
+        List<Integer> input = Arrays.asList(1, 2, 3, 4, 5);
+        List<Integer> expected = Arrays.asList();
+        List<Integer> actual = ListUtils.findDuplicates(input);
+        assertEquals(expected, actual, "The list should be empty as there are no duplicates.");
+    }
+
+    @Test
+    public void testFindDuplicatesEmptyList() {
+        List<Integer> input = Arrays.asList();
+        List<Integer> expected = Arrays.asList();
+        List<Integer> actual = ListUtils.findDuplicates(input);
+        assertEquals(expected, actual, "The list should be empty as the input list is empty.");
+    }
+
+    @Test
+    public void testFindDuplicatesSingleElement() {
+        List<Integer> input = Arrays.asList(1);
+        List<Integer> expected = Arrays.asList();
+        List<Integer> actual = ListUtils.findDuplicates(input);
+        assertEquals(expected, actual, "The list should be empty as there is only one element.");
+    }
+
+    @Test
+    public void testFindDuplicatesMultipleDuplicates() {
+        List<Integer> input = Arrays.asList(1, 1, 2, 2, 3, 3, 4, 4);
+        List<Integer> expected = Arrays.asList(1, 2, 3, 4);
+        List<Integer> actual = ListUtils.findDuplicates(input);
+        assertEquals(expected, actual, "The list should contain all duplicate elements.");
+    }
+
+    @Test
+    public void testFindDuplicatesAllSameElements() {
+        List<Integer> input = Arrays.asList(5, 5, 5, 5);
+        List<Integer> expected = Arrays.asList(5);
+        List<Integer> actual = ListUtils.findDuplicates(input);
+        assertEquals(expected, actual, "The list should contain the single element as all elements are the same.");
+    }
+
     @Test
     public void testGetFirst() {
         assertEquals(a, ListUtils.getFirst(fullList));