diff --git a/src/main/java/org/apache/commons/collections4/IterableUtils.java b/src/main/java/org/apache/commons/collections4/IterableUtils.java index 2a3fb318f2..9c5d58336d 100644 --- a/src/main/java/org/apache/commons/collections4/IterableUtils.java +++ b/src/main/java/org/apache/commons/collections4/IterableUtils.java @@ -83,6 +83,7 @@ public Iterator iterator() { *

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the element type * @param iterable the iterable to limit, may not be null @@ -111,9 +112,11 @@ public Iterator iterator() { * The returned iterable has an iterator that traverses the elements in the order * of the arguments, i.e. iterables[0], iterables[1], .... The source iterators * are not polled until necessary. + *

*

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the element type * @param iterables the iterables to combine, may not be null @@ -144,9 +147,11 @@ protected Iterator nextIterator(final int count) { * The returned iterable has an iterator that traverses the elements in {@code a}, * followed by the elements in {@code b}. The source iterators are not polled until * necessary. + *

*

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the element type * @param a the first iterable, may not be null @@ -166,9 +171,11 @@ public static Iterable chainedIterable(final Iterable a, * The returned iterable has an iterator that traverses the elements in {@code a}, * followed by the elements in {@code b} and {@code c}. The source iterators are * not polled until necessary. + *

*

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the element type * @param a the first iterable, may not be null @@ -190,9 +197,11 @@ public static Iterable chainedIterable(final Iterable a, * The returned iterable has an iterator that traverses the elements in {@code a}, * followed by the elements in {@code b}, {@code c} and {@code d}. The source * iterators are not polled until necessary. + *

*

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the element type * @param a the first iterable, may not be null @@ -240,6 +249,7 @@ static void checkNotNull(final Iterable... iterables) { *

* The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. + *

* * @param the element type * @param comparator the comparator defining an ordering over the elements, @@ -267,6 +277,7 @@ public Iterator iterator() { *

* The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. + *

* * @param the element type * @param a the first iterable, must not be null @@ -294,6 +305,7 @@ public Iterator iterator() { * A {@code null} object will not be passed to the equator, instead a * {@link org.apache.commons.collections4.functors.NullPredicate NullPredicate} * will be used. + *

* * @param the type of object the {@link Iterable} contains * @param iterable the iterable to check, may be null @@ -312,6 +324,7 @@ public static boolean contains(final Iterable iterable, final E * Checks if the object is contained in the given iterable. *

* A {@code null} or empty iterable returns false. + *

* * @param the type of object the {@link Iterable} contains * @param iterable the iterable to check, may be null @@ -329,6 +342,7 @@ public static boolean contains(final Iterable iterable, final Object obje * Counts the number of elements in the input iterable that match the predicate. *

* A {@code null} iterable matches no elements. + *

* * @param the type of object the {@link Iterable} contains * @param input the {@link Iterable} to get the input from, may be null @@ -357,6 +371,7 @@ public static Iterable emptyIfNull(final Iterable iterable) { * Gets an empty iterable. *

* This iterable does not contain any elements. + *

* * @param the element type * @return an empty iterable @@ -384,6 +399,7 @@ private static Iterator emptyIteratorIfNull(final Iterable iterable) { *

* The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. + *

* * @param the element type * @param iterable the iterable to filter, may not be null @@ -407,6 +423,7 @@ public Iterator iterator() { * Finds the first element in the given iterable which matches the given predicate. *

* A {@code null} or empty iterator returns null. + *

* * @param the element type * @param iterable the iterable to search, may be null @@ -454,6 +471,7 @@ public static void forEach(final Iterable iterable, final Closure * If the input iterable is null no change is made. + *

* * @param the type of object the {@link Iterable} contains * @param iterable the iterable to get the input from, may be null @@ -488,6 +506,7 @@ public static int frequency(final Iterable iterable, final T * {@code IndexOutOfBoundsException} if there is no such element. *

* If the {@link Iterable} is a {@link List}, then it will use {@link List#get(int)}. + *

* * @param the type of object in the {@link Iterable}. * @param iterable the {@link Iterable} to get a value from, may be null @@ -508,6 +527,7 @@ public static T get(final Iterable iterable, final int index) { * matches the given predicate. *

* A {@code null} or empty iterable returns -1. + *

* * @param the element type * @param iterable the iterable to search, may be null @@ -523,6 +543,7 @@ public static int indexOf(final Iterable iterable, final Predicate * A {@code null} iterable returns true. + *

* * @param iterable the {@link Iterable to use}, may be null * @return true if the iterable is null or empty, false otherwise @@ -543,6 +564,7 @@ public static boolean isEmpty(final Iterable iterable) { * cycles omit the removed element, which is no longer in {@code iterable}. The * iterator's {@code hasNext()} method returns {@code true} until {@code iterable} * is empty. + *

* * @param the element type * @param iterable the iterable to loop, may not be null @@ -571,6 +593,7 @@ protected Iterator nextIterator(final int count) { * Answers true if a predicate is true for every element of an iterable. *

* A {@code null} or empty iterable returns true. + *

* * @param the type of object the {@link Iterable} contains * @param iterable the {@link Iterable} to use, may be null @@ -587,6 +610,7 @@ public static boolean matchesAll(final Iterable iterable, final Predicate * Answers true if a predicate is true for any element of the iterable. *

* A {@code null} or empty iterable returns false. + *

* * @param the type of object the {@link Iterable} contains * @param iterable the {@link Iterable} to use, may be null @@ -605,6 +629,7 @@ public static boolean matchesAny(final Iterable iterable, final Predicate * For each predicate, the returned list will contain a collection holding * all elements of the input iterable matching the predicate. The last collection * contained in the list will hold all elements which didn't match any predicate: + *

*
      *  [C1, C2, R] = partition(I, P1, P2) with
      *  I = input
@@ -617,14 +642,17 @@ public static  boolean matchesAny(final Iterable iterable, final Predicate
      * 

* Note: elements are only added to the output collection of the first matching * predicate, determined by the order of arguments. + *

*

* If the input iterable is {@code null}, the same is returned as for an * empty iterable. * If no predicates have been provided, all elements of the input collection * will be added to the rejected collection. + *

*

* Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3] * and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]]. + *

* * @param the type of object the {@link Iterable} contains * @param the type of the output {@link Collection} @@ -694,6 +722,7 @@ public static > List partition(final Iterable *
      *  [C1, R] = partition(I, P1) with
      *  I = input
@@ -704,9 +733,11 @@ public static > List partition(final Iterable
      * If the input iterable is {@code null}, the same is returned as for an
      * empty iterable.
+     * 

*

* Example: for an input list [1, 2, 3, 4, 5] calling partition with a predicate [x < 3] * will result in the following output: [[1, 2], [3, 4, 5]]. + *

* * @param the type of object the {@link Iterable} contains * @param iterable the iterable to partition, may be null @@ -731,6 +762,7 @@ public static List> partition(final Iterable iterable, * For each predicate, the result will contain a list holding all elements of the * input iterable matching the predicate. The last list will hold all elements * which didn't match any predicate: + *

*
      *  [C1, C2, R] = partition(I, P1, P2) with
      *  I = input
@@ -743,12 +775,15 @@ public static  List> partition(final Iterable iterable,
      * 

* Note: elements are only added to the output collection of the first matching * predicate, determined by the order of arguments. + *

*

* If the input iterable is {@code null}, the same is returned as for an * empty iterable. + *

*

* Example: for an input list [1, 2, 3, 4, 5] calling partition with predicates [x < 3] * and [x < 5] will result in the following output: [[1, 2], [3, 4], [5]]. + *

* * @param the type of object the {@link Iterable} contains * @param iterable the collection to get the input from, may be null @@ -770,9 +805,11 @@ public static List> partition(final Iterable iterable, * In case the provided iterable is a {@link List} instance, a * {@link ReverseListIterator} will be used to reverse the traversal * order, otherwise an intermediate {@link List} needs to be created. + *

*

* The returned iterable's iterator supports {@code remove()} if the * provided iterable is a {@link List} instance. + *

* * @param the element type * @param iterable the iterable to use, may not be null @@ -797,6 +834,7 @@ public Iterator iterator() { * Returns the number of elements contained in the given iterator. *

* A {@code null} or empty iterator returns {@code 0}. + *

* * @param iterable the iterable to check, may be null * @return the number of elements contained in the iterable @@ -816,6 +854,7 @@ public static int size(final Iterable iterable) { *

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the element type * @param iterable the iterable to use, may not be null @@ -856,6 +895,7 @@ public static List toList(final Iterable iterable) { * enclosed in square brackets ({@code "[]"}). Adjacent elements are separated * by the characters {@code ", "} (a comma followed by a space). Elements are * converted to strings as by {@code String.valueOf(Object)}. + *

* * @param the element type * @param iterable the iterable to convert to a string, may be null @@ -872,6 +912,7 @@ public static String toString(final Iterable iterable) { * enclosed in square brackets ({@code "[]"}). Adjacent elements are separated * by the characters {@code ", "} (a comma followed by a space). Elements are * converted to strings as by using the provided {@code transformer}. + *

* * @param the element type * @param iterable the iterable to convert to a string, may be null @@ -892,6 +933,7 @@ public static String toString(final Iterable iterable, * enclosed by the provided {@code prefix} and {@code suffix}. Adjacent elements * are separated by the provided {@code delimiter}. Elements are converted to * strings as by using the provided {@code transformer}. + *

* * @param the element type * @param iterable the iterable to convert to a string, may be null @@ -917,6 +959,7 @@ public static String toString(final Iterable iterable, *

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the input element type * @param the output element type @@ -943,6 +986,7 @@ public Iterator iterator() { * The returned iterable's iterator supports {@code remove()} when the * corresponding input iterator supports it. Calling {@code remove()} * will only remove a single element from the underlying iterator. + *

* * @param the element type * @param iterable the iterable to use, may not be null @@ -963,6 +1007,7 @@ public Iterator iterator() { * Returns an unmodifiable view of the given iterable. *

* The returned iterable's iterator does not support {@code remove()}. + *

* * @param the element type * @param iterable the iterable to use, may not be null @@ -983,9 +1028,11 @@ public static Iterable unmodifiableIterable(final Iterable iterable) { * The returned iterable has an iterator that traverses the elements in {@code a} * and {@code b} in alternating order. The source iterators are not polled until * necessary. + *

*

* The returned iterable's iterator supports {@code remove()} when the corresponding * input iterator supports it. + *

* * @param the element type * @param a the first iterable, may not be null