Move cardinality method, rename frequency to countMatches.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/collections/trunk@1683914 13f79535-47bb-0310-9956-ffa450edef68

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

@@ -614,29 +614,16 @@ public class CollectionUtils {
      * @param coll the {@link Iterable} to search
      * @param <O> the type of object that the {@link Iterable} may contain.
      * @return the the number of occurrences of obj in coll
+     * @throws NullPointerException if coll is null
+     * @deprecated since 4.1, use {@link IterableUtils#cardinality(Iterable, Object)} instead.
+     *   Be aware that the order of parameters has changed.
      */
+    @Deprecated
     public static <O> int cardinality(final O obj, final Iterable<? super O> coll) {
-        if (coll instanceof Set<?>) {
+        if (coll == null) {
-            return ((Set<? super O>) coll).contains(obj) ? 1 : 0;
+            throw new NullPointerException("coll must not be null.");
         }
-        if (coll instanceof Bag<?>) {
+        return IterableUtils.cardinality(coll, obj);
-            return ((Bag<? super O>) coll).getCount(obj);
-        }
-        int count = 0;
-        if (obj == null) {
-            for (final Object element : coll) {
-                if (element == null) {
-                    count++;
-                }
-            }
-        } else {
-            for (final Object element : coll) {
-                if (obj.equals(element)) {
-                    count++;
-                }
-            }
-        }
-        return count;
     }
 
     /**
@@ -820,11 +807,11 @@ public class CollectionUtils {
      * @param input  the {@link Iterable} to get the input from, may be null
      * @param predicate  the predicate to use, may be null
      * @return the number of matches for the predicate in the collection
-     * @deprecated since 4.1, use {@link IterableUtils#frequency(Iterable, Predicate)} instead
+     * @deprecated since 4.1, use {@link IterableUtils#countMatches(Iterable, Predicate)} instead
      */
     @Deprecated
     public static <C> int countMatches(final Iterable<C> input, final Predicate<? super C> predicate) {
-        return predicate == null ? 0 : (int) IterableUtils.frequency(input, predicate);
+        return predicate == null ? 0 : (int) IterableUtils.countMatches(input, predicate);
     }
 
     /**

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

@@ -22,6 +22,7 @@ import java.util.Collections;
 import java.util.Comparator;
 import java.util.Iterator;
 import java.util.List;
+import java.util.Set;
 
 import org.apache.commons.collections4.functors.EqualPredicate;
 import org.apache.commons.collections4.iterators.LazyIteratorChain;
@@ -238,14 +239,14 @@ public class IterableUtils {
      *
      * @param <E>  the element type
      * @param iterable  the iterable to filter, may be null
-     * @param predicate  the predicate used to filter elements, must not be null
+     * @param predicate  the predicate used to filter elements, may not be null
      * @return a filtered view on the specified iterable
      * @throws NullPointerException if predicate is null
      */
     public static <E> Iterable<E> filteredIterable(final Iterable<E> iterable,
                                                    final Predicate<? super E> predicate) {
         if (predicate == null) {
-            throw new NullPointerException("predicate must not be null.");
+            throw new NullPointerException("Predicate must not be null.");
         }
 
         return new FluentIterable<E>() {
@@ -274,7 +275,7 @@ public class IterableUtils {
      */
     public static <E> Iterable<E> boundedIterable(final Iterable<E> iterable, final long maxSize) {
         if (maxSize < 0) {
-            throw new IllegalArgumentException("maxSize parameter must not be negative.");
+            throw new IllegalArgumentException("MaxSize parameter must not be negative.");
         }
 
         return new FluentIterable<E>() {
@@ -372,7 +373,7 @@ public class IterableUtils {
      */
     public static <E> Iterable<E> skippingIterable(final Iterable<E> iterable, final long elementsToSkip) {
         if (elementsToSkip < 0) {
-            throw new IllegalArgumentException("elementsToSkip parameter must not be negative.");
+            throw new IllegalArgumentException("ElementsToSkip parameter must not be negative.");
         }
 
         return new FluentIterable<E>() {
@@ -403,7 +404,7 @@ public class IterableUtils {
     public static <I, O> Iterable<O> transformedIterable(final Iterable<I> iterable,
                                                          final Transformer<? super I, ? extends O> transformer) {
         if (transformer == null) {
-            throw new NullPointerException("transformer must not be null.");
+            throw new NullPointerException("Transformer must not be null.");
         }
 
         return new FluentIterable<O>() {
@@ -540,13 +541,13 @@ public class IterableUtils {
 
     /**
      * Returns an empty iterator if the argument is <code>null</code>,
-     * or returns {@code iterable.iterator()} otherwise.
+     * or {@code iterable.iterator()} otherwise.
      *
      * @param <E> the element type
      * @param iterable  the iterable, possibly <code>null</code>
-     * @return an empty collection if the argument is <code>null</code>
+     * @return an empty iterator if the argument is <code>null</code>
      */
-    public static <E> Iterator<E> emptyIteratorIfNull(final Iterable<E> iterable) {
+    private static <E> Iterator<E> emptyIteratorIfNull(final Iterable<E> iterable) {
         return iterable != null ? iterable.iterator() : IteratorUtils.<E>emptyIterator();
     }
 
@@ -635,19 +636,11 @@ public class IterableUtils {
      * @return the number of matches for the predicate in the collection
      * @throws NullPointerException if predicate is null
      */
-    public static <E> long frequency(final Iterable<E> input, final Predicate<? super E> predicate) {
+    public static <E> long countMatches(final Iterable<E> input, final Predicate<? super E> predicate) {
         if (predicate == null) {
             throw new NullPointerException("Predicate must not be null.");
         }
-        long count = 0;
+        return size(filteredIterable(input, predicate));
-        if (input != null) {
-            for (final E o : input) {
-                if (predicate.evaluate(o)) {
-                    count++;
-                }
-            }
-        }
-        return count;
     }
 
     /**
@@ -709,6 +702,24 @@ public class IterableUtils {
         return matchesAny(iterable, EqualPredicate.equalPredicate(object, equator));
     }
 
+    /**
+     * Returns the number of occurrences of the provided object in the iterable.
+     *
+     * @param <E>  the type of object that the {@link Iterable} may contain
+     * @param iterable  the {@link Iterable} to search
+     * @param obj  the object to find the cardinality of
+     * @return the the number of occurrences of obj in iterable
+     */
+    public static <E, T extends E> int cardinality(final Iterable<E> iterable, final T obj) {
+        if (iterable instanceof Set<?>) {
+            return ((Set<E>) iterable).contains(obj) ? 1 : 0;
+        }
+        if (iterable instanceof Bag<?>) {
+            return ((Bag<E>) iterable).getCount(obj);
+        }
+        return size(filteredIterable(iterable, EqualPredicate.<E>equalPredicate(obj)));
+    }
+
     /**
      * Returns the <code>index</code>-th value in the <code>iterable</code>'s {@link Iterator}, throwing
      * <code>IndexOutOfBoundsException</code> if there is no such element.

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

@@ -188,6 +188,7 @@ public class CollectionUtilsTest extends MockTestCase {
     }
 
     @Test
+    @Deprecated
     public void cardinality() {
         assertEquals(1, CollectionUtils.cardinality(1, iterableA));
         assertEquals(2, CollectionUtils.cardinality(2, iterableA));
@@ -231,6 +232,7 @@ public class CollectionUtilsTest extends MockTestCase {
     }
 
     @Test
+    @Deprecated
     public void cardinalityOfNull() {
         final List<String> list = new ArrayList<String>();
         assertEquals(0, CollectionUtils.cardinality(null, list));
@@ -671,6 +673,7 @@ public class CollectionUtilsTest extends MockTestCase {
     }
 
     @Test
+    @Deprecated
     public void forAllButLastDoCollection() {
         final Closure<List<? extends Number>> testClosure = ClosureUtils.invokerClosure("clear");
         final Collection<List<? extends Number>> col = new ArrayList<List<? extends Number>>();

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

@@ -20,10 +20,13 @@ import static org.apache.commons.collections4.functors.EqualPredicate.*;
 import static org.junit.Assert.*;
 
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.HashSet;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.Set;
 
 import org.apache.commons.collections4.bag.HashBag;
 import org.junit.Assert;
@@ -197,6 +200,72 @@ public class IterableUtilsTest {
         } // this is what we want
     }
 
+    @Test
+    public void cardinality() {
+        // null iterable test
+        assertEquals(0, IterableUtils.cardinality(null, 1));
+
+        assertEquals(1, IterableUtils.cardinality(iterableA, 1));
+        assertEquals(2, IterableUtils.cardinality(iterableA, 2));
+        assertEquals(3, IterableUtils.cardinality(iterableA, 3));
+        assertEquals(4, IterableUtils.cardinality(iterableA, 4));
+        assertEquals(0, IterableUtils.cardinality(iterableA, 5));
+
+        assertEquals(0, IterableUtils.cardinality(iterableB, 1L));
+        assertEquals(4, IterableUtils.cardinality(iterableB, 2L));
+        assertEquals(3, IterableUtils.cardinality(iterableB, 3L));
+        assertEquals(2, IterableUtils.cardinality(iterableB, 4L));
+        assertEquals(1, IterableUtils.cardinality(iterableB, 5L));
+
+        // Ensure that generic bounds accept valid parameters, but return
+        // expected results
+        // e.g. no longs in the "int" Iterable<Number>, and vice versa.
+        Iterable<Number> iterableIntAsNumber = Arrays.<Number>asList(1, 2, 3, 4, 5);
+        Iterable<Number> iterableLongAsNumber = Arrays.<Number>asList(1L, 2L, 3L, 4L, 5L);
+        assertEquals(0, IterableUtils.cardinality(iterableIntAsNumber, 2L));
+        assertEquals(0, IterableUtils.cardinality(iterableLongAsNumber, 2));
+
+        final Set<String> set = new HashSet<String>();
+        set.add("A");
+        set.add("C");
+        set.add("E");
+        set.add("E");
+        assertEquals(1, IterableUtils.cardinality(set, "A"));
+        assertEquals(0, IterableUtils.cardinality(set, "B"));
+        assertEquals(1, IterableUtils.cardinality(set, "C"));
+        assertEquals(0, IterableUtils.cardinality(set, "D"));
+        assertEquals(1, IterableUtils.cardinality(set, "E"));
+
+        final Bag<String> bag = new HashBag<String>();
+        bag.add("A", 3);
+        bag.add("C");
+        bag.add("E");
+        bag.add("E");
+        assertEquals(3, IterableUtils.cardinality(bag, "A"));
+        assertEquals(0, IterableUtils.cardinality(bag, "B"));
+        assertEquals(1, IterableUtils.cardinality(bag, "C"));
+        assertEquals(0, IterableUtils.cardinality(bag, "D"));
+        assertEquals(2, IterableUtils.cardinality(bag, "E"));
+    }
+
+    @Test
+    public void cardinalityOfNull() {
+        final List<String> list = new ArrayList<String>();
+        assertEquals(0, IterableUtils.cardinality(list, null));
+        list.add("A");
+        assertEquals(0, IterableUtils.cardinality(list, null));
+        list.add(null);
+        assertEquals(1, IterableUtils.cardinality(list, null));
+        list.add("B");
+        assertEquals(1, IterableUtils.cardinality(list, null));
+        list.add(null);
+        assertEquals(2, IterableUtils.cardinality(list, null));
+        list.add("B");
+        assertEquals(2, IterableUtils.cardinality(list, null));
+        list.add(null);
+        assertEquals(3, IterableUtils.cardinality(list, null));
+    }
+
     @Test
     public void find() {
         Predicate<Number> testPredicate = equalPredicate((Number) 4);
@@ -215,19 +284,19 @@ public class IterableUtilsTest {
     }
 
     @Test
-    public void frequency() {
+    public void countMatches() {
-        assertEquals(4, IterableUtils.frequency(iterableB, EQUALS_TWO));
+        assertEquals(4, IterableUtils.countMatches(iterableB, EQUALS_TWO));
-        assertEquals(0, IterableUtils.frequency(null, EQUALS_TWO));
+        assertEquals(0, IterableUtils.countMatches(null, EQUALS_TWO));
 
         try {
-            assertEquals(0, IterableUtils.frequency(iterableA, null));
+            assertEquals(0, IterableUtils.countMatches(iterableA, null));
             fail("predicate must not be null");
         } catch (NullPointerException ex) {
             // expected
         }
 
         try {
-            assertEquals(0, IterableUtils.frequency(null, null));
+            assertEquals(0, IterableUtils.countMatches(null, null));
             fail("predicate must not be null");
         } catch (NullPointerException ex) {
             // expected