diff --git a/src/java/org/apache/commons/collections/CollectionUtils.java b/src/java/org/apache/commons/collections/CollectionUtils.java index 4a07bbdf7..d2190cb0f 100644 --- a/src/java/org/apache/commons/collections/CollectionUtils.java +++ b/src/java/org/apache/commons/collections/CollectionUtils.java @@ -1,5 +1,5 @@ /* - * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/CollectionUtils.java,v 1.42 2003/09/21 16:26:08 scolebourne Exp $ + * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/CollectionUtils.java,v 1.43 2003/09/21 23:47:09 psteitz Exp $ * ==================================================================== * * The Apache Software License, Version 1.1 @@ -84,7 +84,7 @@ import org.apache.commons.collections.observed.ObservableCollection; * Provides utility methods and decorators for {@link Collection} instances. * * @since Commons Collections 1.0 - * @version $Revision: 1.42 $ $Date: 2003/09/21 16:26:08 $ + * @version $Revision: 1.43 $ $Date: 2003/09/21 23:47:09 $ * * @author Rodney Waldhoff * @author Paul Jack @@ -94,6 +94,7 @@ import org.apache.commons.collections.observed.ObservableCollection; * @author Peter KoBek * @author Matthew Hawthorne * @author Janek Bogucki + * @author Phil Steitz */ public class CollectionUtils { @@ -122,6 +123,9 @@ public class CollectionUtils { * will be equal to the maximum of the cardinality of that element * in the two given {@link Collection}s. * + * @param a the first collection, must not be null + * @param b the second collection, must not be null + * @return the union of the two collections * @see Collection#addAll */ public static Collection union(final Collection a, final Collection b) { @@ -148,6 +152,9 @@ public class CollectionUtils { * will be equal to the minimum of the cardinality of that element * in the two given {@link Collection}s. * + * @param a the first collection, must not be null + * @param b the second collection, must not be null + * @return the intersection of the two collections * @see Collection#retainAll * @see #containsAny */ @@ -179,6 +186,10 @@ public class CollectionUtils { * {@link #subtract subtract}({@link #union union(a,b)},{@link #intersection intersection(a,b)}) * or * {@link #union union}({@link #subtract subtract(a,b)},{@link #subtract subtract(b,a)}). + * + * @param a the first collection, must not be null + * @param b the second collection, must not be null + * @return the symmetric difference of the two collections */ public static Collection disjunction(final Collection a, final Collection b) { ArrayList list = new ArrayList(); @@ -252,7 +263,7 @@ public class CollectionUtils { * Only those elements present in the collection will appear as * keys in the map. * - * @param coll the collection to get the cardinality map for + * @param coll the collection to get the cardinality map for, must not be null * @return the populated cardinality map */ public static Map getCardinalityMap(final Collection coll) { @@ -275,6 +286,9 @@ public class CollectionUtils { * than or equal to the cardinality of e in b, * for each element e in a. * + * @param a the first (sub?) collection, must not be null + * @param b the second (super?) collection, must not be null + * @return true iff a is a sub-collection of b * @see #isProperSubCollection * @see Collection#containsAll */ @@ -306,6 +320,9 @@ public class CollectionUtils { *
  • a.size() < Integer.MAXVALUE
    • * * + * @param a the first (sub?) collection, must not be null + * @param b the second (super?) collection, must not be null + * @return true iff a is a proper sub-collection of b * @see #isSubCollection * @see Collection#containsAll */ @@ -315,11 +332,15 @@ public class CollectionUtils { /** * Returns true iff the given {@link Collection}s contain - * exactly the same elements with exactly the same cardinality. + * exactly the same elements with exactly the same cardinalities. *

    * That is, iff the cardinality of e in a is * equal to the cardinality of e in b, * for each element e in a or b. + * + * @param a the first collection, must not be null + * @param b the second collection, must not be null + * @return true iff the collections contain the same elements with the same cardinalities. */ public static boolean isEqualCollection(final Collection a, final Collection b) { if(a.size() != b.size()) { @@ -345,6 +366,10 @@ public class CollectionUtils { /** * Returns the number of occurrences of obj * in col. + * + * @param obj the object to find the cardinality of + * @param col the collection to search + * @return the the number of occurrences of obj in col */ public static int cardinality(Object obj, final Collection col) { int count = 0; @@ -367,7 +392,8 @@ public class CollectionUtils { /** * Finds the first element in the given collection which matches the given predicate. *

    - * If the input collection or predicate is null, null is returned. + * If the input collection or predicate is null, or no element of the collection + * matches the predicate, null is returned. * * @param collection the collection to search, may be null * @param predicate the predicate to use, may be null @@ -425,8 +451,9 @@ public class CollectionUtils { *

    * If the input collection or transformer is null, there is no change made. *

    - * This routine is best for Lists and uses set(), however it adapts for all - * Collections that support clear() and addAll(). + * This routine is best for Lists, for which set() is used to do the + * transformations "in place." For other Collections, clear() and addAll() + * are used to replace elements. *

    * If the input collection controls its input, such as a Set, and the * Transformer creates duplicates (or are otherwise invalid), the @@ -569,8 +596,8 @@ public class CollectionUtils { } /** - * Transforms all elements from inputCollection with the given transformer - * and adds them to the outputCollection. + * Returns a new Collection consisting of the elements of inputCollection transformed + * by the given transformer. *

    * If the input transformer is null, the result is an empty list. * @@ -586,7 +613,7 @@ public class CollectionUtils { } /** - * Transforms all elements from the inputIterator with the given transformer + * Transforms all elements from the inputIterator with the given transformer * and adds them to the outputCollection. *

    * If the input iterator or transformer is null, the result is an empty list. @@ -674,8 +701,8 @@ public class CollectionUtils { /** * Adds all elements in the array to the given collection. * - * @param collection the collection to add to - * @param elements the array of elements to add, may be null + * @param collection the collection to add to, may not be null + * @param elements the array of elements to add, may not be null * @throws NullPointerException if the collection or array is null */ public static void addAll(Collection collection, Object[] elements) { @@ -685,33 +712,41 @@ public class CollectionUtils { } /** - * Given an Object, and an index, it will get the nth value in the + * Given an Object, and an index, returns the nth value in the * object. *

    * - * @param obj the object to get an index of + * @param obj the object to get an index of, may be null * @param idx the index to get * @throws IndexOutOfBoundsException - * @throws NoSuchElementException + * @throws ArrayIndexOutOfBoundsException */ public static Object index(Object obj, int idx) { return index(obj, new Integer(idx)); } /** - * Given an Object, and a key (index), it will get value associated with + * Given an Object, and a key (index), returns the value associated with * that key in the Object. The following checks are made: * * @@ -719,7 +754,7 @@ public class CollectionUtils { * @param index the index to get * @return the object at the specified index * @throws IndexOutOfBoundsException - * @throws NoSuchElementException + * @throws ArrayIndexOutOfBoundsException */ public static Object index(Object obj, Object index) { if(obj instanceof Map) {