psteitz 2003/10/15 23:04:56 Modified: collections/src/java/org/apache/commons/collections ComparatorUtils.java Log: javadoc Revision Changes Path 1.10 +27 -31 jakarta-commons/collections/src/java/org/apache/commons/collections/ComparatorUtils.java Index: ComparatorUtils.java =================================================================== RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/ComparatorUtils.java,v retrieving revision 1.9 retrieving revision 1.10 diff -u -r1.9 -r1.10 --- ComparatorUtils.java 5 Sep 2003 03:35:06 -0000 1.9 +++ ComparatorUtils.java 16 Oct 2003 06:04:56 -0000 1.10 @@ -71,14 +71,10 @@ * Provides convenient static utility methods for <Code>Comparator</Code> * objects. * <p> - * Most of the utility in this class can also be found in the + * Most of the functionality in this class can also be found in the * <code>comparators</code> package. This class merely provides a * convenient central place if you have use for more than one class * in the <code>comparators</code> subpackage. - * <p> - * Note that <i>every</i> method in this class allows you to specify - * <code>null</code> instead of a comparator, in which case - * [EMAIL PROTECTED] #NATURAL_COMPARATOR} will be used. * * @since Commons Collections 2.1 * @version $Revision$ $Date$ @@ -89,7 +85,7 @@ public class ComparatorUtils { /** - * ComparatorUtils should not normally be constructed. + * ComparatorUtils should not normally be instantiated. */ public ComparatorUtils() { } @@ -113,27 +109,26 @@ /** * Gets a comparator that compares using two [EMAIL PROTECTED] Comparator}s. * <p> - * The second comparator is used if the first comparator returns - * that equal. + * The second comparator is used if the first comparator returns equal. * * @param comparator1 the first comparator to use, not null * @param comparator2 the first comparator to use, not null - * @return a combination comparator over the comparators + * @return a [EMAIL PROTECTED] ComparatorChain} formed from the two comparators * @throws NullPointerException if either comparator is null + * @see ComparatorChain */ public static Comparator chainedComparator(Comparator comparator1, Comparator comparator2) { return chainedComparator(new Comparator[] {comparator1, comparator2}); } /** - * Gets a comparator that compares using an array of [EMAIL PROTECTED] Comparator}s. - * <p> - * The second comparator is used if the first comparator returns - * that equal and so on. + * Gets a comparator that compares using an array of [EMAIL PROTECTED] Comparator}s, applied + * in sequence until one returns not equal or the array is exhausted. * - * @param comparators the comparators to use, not null or empty or contain nulls - * @return a combination comparator over the comparators + * @param comparators the comparators to use, not null or empty or containing nulls + * @return a [EMAIL PROTECTED] ComparatorChain} formed from the input comparators * @throws NullPointerException if comparators array is null or contains a null + * @see ComparatorChain */ public static Comparator chainedComparator(Comparator[] comparators) { ComparatorChain chain = new ComparatorChain(); @@ -147,15 +142,15 @@ } /** - * Gets a comparator that compares using a collection of [EMAIL PROTECTED] Comparator}s. - * <p> - * The second comparator is used if the first comparator returns - * that equal and so on. + * Gets a comparator that compares using a collection of [EMAIL PROTECTED] Comparator}s, + * applied in (default iterator) sequence until one returns not equal or the + * collection is exhausted. * - * @param comparators the comparators to use, not null or empty or contain nulls - * @return a combination comparator over the comparators + * @param comparators the comparators to use, not null or empty or containing nulls + * @return a [EMAIL PROTECTED] ComparatorChain} formed from the input comparators * @throws NullPointerException if comparators collection is null or contains a null * @throws ClassCastException if the comparators collection contains the wrong object type + * @see ComparatorChain */ public static Comparator chainedComparator(Collection comparators) { return chainedComparator( @@ -164,11 +159,10 @@ } /** - * Gets a comparator that reverses the order of the given - * comparator. + * Gets a comparator that reverses the order of the given comparator. * - * @param comparator the comparator whose order to reverse - * @return a comparator who reverses that order + * @param comparator the comparator to reverse + * @return a comparator that reverses the order of the input comparator * @see ReverseComparator */ public static Comparator reversedComparator(Comparator comparator) { @@ -199,7 +193,7 @@ * <p> * The returned comparator will consider a null value to be less than * any nonnull value, and equal to any other null value. Two nonnull - * values will be evaluated with the given comparator.<P> + * values will be evaluated with the given comparator. * * @param comparator the comparator that wants to allow nulls * @return a version of that comparator that allows nulls @@ -217,7 +211,7 @@ * <p> * The returned comparator will consider a null value to be greater than * any nonnull value, and equal to any other null value. Two nonnull - * values will be evaluated with the given comparator.<P> + * values will be evaluated with the given comparator. * * @param comparator the comparator that wants to allow nulls * @return a version of that comparator that allows nulls @@ -251,7 +245,8 @@ /** * Returns the smaller of the given objects according to the given - * comparator. + * comparator, returning the second object if the comparator + * returns equal. * * @param o1 the first object to compare * @param o2 the second object to compare @@ -267,13 +262,14 @@ } /** - * Returns the smaller of the given objects according to the given - * comparator. + * Returns the larger of the given objects according to the given + * comparator, returning the second object if the comparator + * returns equal. * * @param o1 the first object to compare * @param o2 the second object to compare * @param comparator the sort order to use - * @return the smaller of the two objects + * @return the larger of the two objects */ public static Object max(Object o1, Object o2, Comparator comparator) { if (comparator == null) {
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]