Rename cardinatlity to frequency, apply to forEach, add empty and singleton methods to FluentIterable.

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

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

@@ -615,7 +615,7 @@ public class CollectionUtils {
      * @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.
+     * @deprecated since 4.1, use {@link IterableUtils#frequency(Iterable, Object)} instead.
      *   Be aware that the order of parameters has changed.
      */
     @Deprecated
@@ -623,7 +623,7 @@ public class CollectionUtils {
         if (coll == null) {
             throw new NullPointerException("coll must not be null.");
         }
-        return IterableUtils.cardinality(coll, obj);
+        return IterableUtils.frequency(coll, obj);
     }
 
     /**
@@ -653,12 +653,12 @@ public class CollectionUtils {
      * @param collection  the collection to get the input from, may be null
      * @param closure  the closure to perform, may be null
      * @return closure
-     * @deprecated since 4.1, use {@link IterableUtils#apply(Iterable, Closure)} instead
+     * @deprecated since 4.1, use {@link IterableUtils#forEach(Iterable, Closure)} instead
      */
     @Deprecated
     public static <T, C extends Closure<? super T>> C forAllDo(final Iterable<T> collection, final C closure) {
         if (closure != null) {
-            IterableUtils.apply(collection, closure);
+            IterableUtils.forEach(collection, closure);
         }
         return closure;
     }
@@ -674,12 +674,12 @@ public class CollectionUtils {
      * @param closure  the closure to perform, may be null
      * @return closure
      * @since 4.0
-     * @deprecated since 4.1, use {@link IteratorUtils#apply(Iterator, Closure)} instead
+     * @deprecated since 4.1, use {@link IteratorUtils#forEach(Iterator, Closure)} instead
      */
     @Deprecated
     public static <T, C extends Closure<? super T>> C forAllDo(final Iterator<T> iterator, final C closure) {
         if (closure != null) {
-            IteratorUtils.apply(iterator, closure);
+            IteratorUtils.forEach(iterator, closure);
         }
         return closure;
     }
@@ -695,12 +695,12 @@ public class CollectionUtils {
      * @param closure  the closure to perform, may be null
      * @return the last element in the collection, or null if either collection or closure is null
      * @since 4.0
-     * @deprecated since 4.1, use {@link IterableUtils#applyForAllButLast(Iterable, Closure)} instead
+     * @deprecated since 4.1, use {@link IterableUtils#forEachButLast(Iterable, Closure)} instead
      */
     @Deprecated
     public static <T, C extends Closure<? super T>> T forAllButLastDo(final Iterable<T> collection,
                                                                       final C closure) {
-        return closure != null ? IterableUtils.applyForAllButLast(collection, closure) : null;
+        return closure != null ? IterableUtils.forEachButLast(collection, closure) : null;
     }
 
     /**
@@ -714,11 +714,11 @@ public class CollectionUtils {
      * @param closure  the closure to perform, may be null
      * @return the last element in the collection, or null if either iterator or closure is null
      * @since 4.0
-     * @deprecated since 4.1, use {@link IteratorUtils#applyForAllButLast(Iterator, Closure)} instead
+     * @deprecated since 4.1, use {@link IteratorUtils#forEachButLast(Iterator, Closure)} instead
      */
     @Deprecated
     public static <T, C extends Closure<? super T>> T forAllButLastDo(final Iterator<T> iterator, final C closure) {
-        return closure != null ? IteratorUtils.applyForAllButLast(iterator, closure) : null;
+        return closure != null ? IteratorUtils.forEachButLast(iterator, closure) : null;
     }
 
     /**

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

@@ -23,6 +23,8 @@ import java.util.Enumeration;
 import java.util.Iterator;
 import java.util.List;
 
+import org.apache.commons.collections4.iterators.SingletonIterator;
+
 /**
  * A FluentIterable provides a powerful yet simple API for manipulating
  * Iterable instances in a fluent manner.
@@ -69,6 +71,30 @@ public class FluentIterable<E> implements Iterable<E> {
     // Static factory methods
     // ----------------------------------------------------------------------
 
+    /**
+     * Creates a new empty FluentIterable.
+     *
+     * @param <T>  the element type
+     * @return a new empty FluentIterable
+     */
+    @SuppressWarnings("unchecked")
+    public static <T> FluentIterable<T> empty() {
+        return IterableUtils.EMPTY_ITERABLE;
+    }
+
+    /**
+     * Creates a new FluentIterable of the single provided element.
+     * <p>
+     * The returned iterable's iterator does not support {@code remove()}.
+     *
+     * @param <T>  the element type
+     * @param singleton  the singleton element
+     * @return a new FluentIterable containing the singleton
+     */
+    public static <T> FluentIterable<T> of(final T singleton) {
+        return of(IteratorUtils.asIterable(new SingletonIterator<T>(singleton, false)));
+    }
+
     /**
      * Creates a new FluentIterable from the provided elements.
      * <p>
@@ -356,16 +382,6 @@ public class FluentIterable<E> implements Iterable<E> {
         return IteratorUtils.asEnumeration(iterator());
     }
 
-    /**
-     * Applies the closure to all elements contained in this iterable.
-     *
-     * @param closure  the closure to apply to each element, may not be null
-     * @throws NullPointerException if closure is null
-     */
-    public void apply(final Closure<? super E> closure) {
-        IterableUtils.apply(iterable, closure);
-    }
-
     /**
      * Checks if all elements contained in this iterable are matching the
      * provided predicate.
@@ -414,6 +430,16 @@ public class FluentIterable<E> implements Iterable<E> {
         return IterableUtils.contains(iterable, object);
     }
 
+    /**
+     * Applies the closure to all elements contained in this iterable.
+     *
+     * @param closure  the closure to apply to each element, may not be null
+     * @throws NullPointerException if closure is null
+     */
+    public void forEach(final Closure<? super E> closure) {
+        IterableUtils.forEach(iterable, closure);
+    }
+
     /**
      * Returns the element at the provided position in this iterable.
      * In order to return the element, an iterator needs to be traversed

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

@@ -559,8 +559,8 @@ public class IterableUtils {
      * @param closure  the closure to apply to each element, may not be null
      * @throws NullPointerException if closure is null
      */
-    public static <E> void apply(final Iterable<E> iterable, final Closure<? super E> closure) {
+    public static <E> void forEach(final Iterable<E> iterable, final Closure<? super E> closure) {
-        IteratorUtils.apply(emptyIteratorIfNull(iterable), closure);
+        IteratorUtils.forEach(emptyIteratorIfNull(iterable), closure);
     }
 
     /**
@@ -574,9 +574,8 @@ public class IterableUtils {
      * @param closure  the closure to perform, may not be null
      * @return the last element in the iterable, or null if iterable is null or empty
      */
-    public static <E, C extends Closure<? super E>> E applyForAllButLast(final Iterable<E> iterable,
+    public static <E> E forEachButLast(final Iterable<E> iterable, final Closure<? super E> closure) {
-                                                                         final C closure) {
+        return IteratorUtils.forEachButLast(emptyIteratorIfNull(iterable), closure);
-        return IteratorUtils.applyForAllButLast(emptyIteratorIfNull(iterable), closure);
     }
 
     /**
@@ -710,7 +709,7 @@ public class IterableUtils {
      * @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) {
+    public static <E, T extends E> int frequency(final Iterable<E> iterable, final T obj) {
         if (iterable instanceof Set<?>) {
             return ((Set<E>) iterable).contains(obj) ? 1 : 0;
         }

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

@@ -1238,7 +1238,7 @@ public class IteratorUtils {
      * @throws NullPointerException if closure is null
      * @since 4.1
      */
-    public static <E> void apply(final Iterator<E> iterator, final Closure<? super E> closure) {
+    public static <E> void forEach(final Iterator<E> iterator, final Closure<? super E> closure) {
         if (closure == null) {
             throw new NullPointerException("Closure must not be null");
         }
@@ -1264,8 +1264,7 @@ public class IteratorUtils {
      * @throws NullPointerException if closure is null
      * @since 4.1
      */
-    public static <E, C extends Closure<? super E>> E applyForAllButLast(final Iterator<E> iterator,
+    public static <E> E forEachButLast(final Iterator<E> iterator, final Closure<? super E> closure) {
-                                                                         final C closure) {
         if (closure == null) {
             throw new NullPointerException("Closure must not be null.");
         }

src/main/java/org/apache/commons/collections4/iterators/IteratorIterable.java

@@ -66,8 +66,7 @@ public class IteratorIterable<E> implements Iterable<E> {
      * Factory method to create an {@link Iterator Iterator} from another
      * iterator over objects of a different subtype.
      */
-    private static <E> Iterator<E> createTypesafeIterator(
+    private static <E> Iterator<E> createTypesafeIterator(final Iterator<? extends E> iterator) {
-            final Iterator<? extends E> iterator) {
         return new Iterator<E>() {
             public boolean hasNext() {
                 return iterator.hasNext();

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

@@ -101,7 +101,7 @@ public class IterableUtilsTest {
 
     // -----------------------------------------------------------------------
     @Test
-    public void apply() {
+    public void forEach() {
         final List<Integer> listA = new ArrayList<Integer>();
         listA.add(1);
 
@@ -112,32 +112,32 @@ public class IterableUtilsTest {
         final Collection<List<Integer>> col = new ArrayList<List<Integer>>();
         col.add(listA);
         col.add(listB);
-        IterableUtils.apply(col, testClosure);
+        IterableUtils.forEach(col, testClosure);
         assertTrue(listA.isEmpty() && listB.isEmpty());
         try {
-            IterableUtils.apply(col, null);
+            IterableUtils.forEach(col, null);
             fail("expecting NullPointerException");
         } catch (NullPointerException npe) {
             // expected
         }
 
-        IterableUtils.apply(null, testClosure);
+        IterableUtils.forEach(null, testClosure);
 
         // null should be OK
         col.add(null);
-        IterableUtils.apply(col, testClosure);
+        IterableUtils.forEach(col, testClosure);
     }
 
     @Test(expected = FunctorException.class)
-    public void applyFailure() {
+    public void forEachFailure() {
         final Closure<String> testClosure = ClosureUtils.invokerClosure("clear");
         final Collection<String> col = new ArrayList<String>();
         col.add("x");
-        IterableUtils.apply(col, testClosure);
+        IterableUtils.forEach(col, testClosure);
     }
 
     @Test
-    public void applyForAllButLast() {
+    public void forEachButLast() {
         final List<Integer> listA = new ArrayList<Integer>();
         listA.add(1);
 
@@ -148,23 +148,23 @@ public class IterableUtilsTest {
         final Collection<List<Integer>> col = new ArrayList<List<Integer>>();
         col.add(listA);
         col.add(listB);
-        List<Integer> last = IterableUtils.applyForAllButLast(col, testClosure);
+        List<Integer> last = IterableUtils.forEachButLast(col, testClosure);
         assertTrue(listA.isEmpty() && !listB.isEmpty());
         assertSame(listB, last);
 
         try {
-            IterableUtils.apply(col, null);
+            IterableUtils.forEachButLast(col, null);
             fail("expecting NullPointerException");
         } catch (NullPointerException npe) {
             // expected
         }
 
-        IterableUtils.apply(null, testClosure);
+        IterableUtils.forEachButLast(null, testClosure);
 
         // null should be OK
         col.add(null);
         col.add(null);
-        last = IterableUtils.applyForAllButLast(col, testClosure);
+        last = IterableUtils.forEachButLast(col, testClosure);
         assertNull(last);
     }
 
@@ -201,69 +201,69 @@ public class IterableUtilsTest {
     }
 
     @Test
-    public void cardinality() {
+    public void frequency() {
         // null iterable test
-        assertEquals(0, IterableUtils.cardinality(null, 1));
+        assertEquals(0, IterableUtils.frequency(null, 1));
 
-        assertEquals(1, IterableUtils.cardinality(iterableA, 1));
+        assertEquals(1, IterableUtils.frequency(iterableA, 1));
-        assertEquals(2, IterableUtils.cardinality(iterableA, 2));
+        assertEquals(2, IterableUtils.frequency(iterableA, 2));
-        assertEquals(3, IterableUtils.cardinality(iterableA, 3));
+        assertEquals(3, IterableUtils.frequency(iterableA, 3));
-        assertEquals(4, IterableUtils.cardinality(iterableA, 4));
+        assertEquals(4, IterableUtils.frequency(iterableA, 4));
-        assertEquals(0, IterableUtils.cardinality(iterableA, 5));
+        assertEquals(0, IterableUtils.frequency(iterableA, 5));
 
-        assertEquals(0, IterableUtils.cardinality(iterableB, 1L));
+        assertEquals(0, IterableUtils.frequency(iterableB, 1L));
-        assertEquals(4, IterableUtils.cardinality(iterableB, 2L));
+        assertEquals(4, IterableUtils.frequency(iterableB, 2L));
-        assertEquals(3, IterableUtils.cardinality(iterableB, 3L));
+        assertEquals(3, IterableUtils.frequency(iterableB, 3L));
-        assertEquals(2, IterableUtils.cardinality(iterableB, 4L));
+        assertEquals(2, IterableUtils.frequency(iterableB, 4L));
-        assertEquals(1, IterableUtils.cardinality(iterableB, 5L));
+        assertEquals(1, IterableUtils.frequency(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.frequency(iterableIntAsNumber, 2L));
-        assertEquals(0, IterableUtils.cardinality(iterableLongAsNumber, 2));
+        assertEquals(0, IterableUtils.frequency(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(1, IterableUtils.frequency(set, "A"));
-        assertEquals(0, IterableUtils.cardinality(set, "B"));
+        assertEquals(0, IterableUtils.frequency(set, "B"));
-        assertEquals(1, IterableUtils.cardinality(set, "C"));
+        assertEquals(1, IterableUtils.frequency(set, "C"));
-        assertEquals(0, IterableUtils.cardinality(set, "D"));
+        assertEquals(0, IterableUtils.frequency(set, "D"));
-        assertEquals(1, IterableUtils.cardinality(set, "E"));
+        assertEquals(1, IterableUtils.frequency(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(3, IterableUtils.frequency(bag, "A"));
-        assertEquals(0, IterableUtils.cardinality(bag, "B"));
+        assertEquals(0, IterableUtils.frequency(bag, "B"));
-        assertEquals(1, IterableUtils.cardinality(bag, "C"));
+        assertEquals(1, IterableUtils.frequency(bag, "C"));
-        assertEquals(0, IterableUtils.cardinality(bag, "D"));
+        assertEquals(0, IterableUtils.frequency(bag, "D"));
-        assertEquals(2, IterableUtils.cardinality(bag, "E"));
+        assertEquals(2, IterableUtils.frequency(bag, "E"));
     }
 
     @Test
-    public void cardinalityOfNull() {
+    public void frequencyOfNull() {
         final List<String> list = new ArrayList<String>();
-        assertEquals(0, IterableUtils.cardinality(list, null));
+        assertEquals(0, IterableUtils.frequency(list, null));
         list.add("A");
-        assertEquals(0, IterableUtils.cardinality(list, null));
+        assertEquals(0, IterableUtils.frequency(list, null));
         list.add(null);
-        assertEquals(1, IterableUtils.cardinality(list, null));
+        assertEquals(1, IterableUtils.frequency(list, null));
         list.add("B");
-        assertEquals(1, IterableUtils.cardinality(list, null));
+        assertEquals(1, IterableUtils.frequency(list, null));
         list.add(null);
-        assertEquals(2, IterableUtils.cardinality(list, null));
+        assertEquals(2, IterableUtils.frequency(list, null));
         list.add("B");
-        assertEquals(2, IterableUtils.cardinality(list, null));
+        assertEquals(2, IterableUtils.frequency(list, null));
         list.add(null);
-        assertEquals(3, IterableUtils.cardinality(list, null));
+        assertEquals(3, IterableUtils.frequency(list, null));
     }
 
     @Test

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

@@ -970,7 +970,7 @@ public class IteratorUtilsTest {
 
     // -----------------------------------------------------------------------
     @Test
-    public void apply() {
+    public void forEach() {
         final List<Integer> listA = new ArrayList<Integer>();
         listA.add(1);
 
@@ -981,24 +981,24 @@ public class IteratorUtilsTest {
         final Collection<List<Integer>> col = new ArrayList<List<Integer>>();
         col.add(listA);
         col.add(listB);
-        IteratorUtils.apply(col.iterator(), testClosure);
+        IteratorUtils.forEach(col.iterator(), testClosure);
         assertTrue(listA.isEmpty() && listB.isEmpty());
         try {
-            IteratorUtils.apply(col.iterator(), null);
+            IteratorUtils.forEach(col.iterator(), null);
             fail("expecting NullPointerException");
         } catch (NullPointerException npe) {
             // expected
         }
 
-        IteratorUtils.apply(null, testClosure);
+        IteratorUtils.forEach(null, testClosure);
 
         // null should be OK
         col.add(null);
-        IteratorUtils.apply(col.iterator(), testClosure);
+        IteratorUtils.forEach(col.iterator(), testClosure);
     }
 
     @Test
-    public void applyForAllButLast() {
+    public void forEachButLast() {
         final List<Integer> listA = new ArrayList<Integer>();
         listA.add(1);
 
@@ -1009,23 +1009,23 @@ public class IteratorUtilsTest {
         final Collection<List<Integer>> col = new ArrayList<List<Integer>>();
         col.add(listA);
         col.add(listB);
-        List<Integer> last = IteratorUtils.applyForAllButLast(col.iterator(), testClosure);
+        List<Integer> last = IteratorUtils.forEachButLast(col.iterator(), testClosure);
         assertTrue(listA.isEmpty() && !listB.isEmpty());
         assertSame(listB, last);
 
         try {
-            IteratorUtils.apply(col.iterator(), null);
+            IteratorUtils.forEachButLast(col.iterator(), null);
             fail("expecting NullPointerException");
         } catch (NullPointerException npe) {
             // expected
         }
 
-        IteratorUtils.apply(null, testClosure);
+        IteratorUtils.forEachButLast(null, testClosure);
 
         // null should be OK
         col.add(null);
         col.add(null);
-        last = IteratorUtils.applyForAllButLast(col.iterator(), testClosure);
+        last = IteratorUtils.forEachButLast(col.iterator(), testClosure);
         assertNull(last);
     }