From 49f3fe1be6fd692b6b8632d62b0bfa34f74e6308 Mon Sep 17 00:00:00 2001 From: Stephen Colebourne Date: Sat, 17 Aug 2002 12:06:56 +0000 Subject: [PATCH] Rename methods Add chainedComparator git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130790 13f79535-47bb-0310-9956-ffa450edef68 --- .../commons/collections/ComparatorUtils.java | 216 ++++++++++++------ 1 file changed, 141 insertions(+), 75 deletions(-) diff --git a/src/java/org/apache/commons/collections/ComparatorUtils.java b/src/java/org/apache/commons/collections/ComparatorUtils.java index 356da0215..7e02b8a39 100644 --- a/src/java/org/apache/commons/collections/ComparatorUtils.java +++ b/src/java/org/apache/commons/collections/ComparatorUtils.java @@ -51,118 +51,181 @@ * information on the Apache Software Foundation, please see * . */ - package org.apache.commons.collections; - +import java.util.Collection; import java.util.Comparator; + import org.apache.commons.collections.comparators.ComparableComparator; -import org.apache.commons.collections.comparators.ReverseComparator; +import org.apache.commons.collections.comparators.ComparatorChain; import org.apache.commons.collections.comparators.NullComparator; +import org.apache.commons.collections.comparators.ReverseComparator; import org.apache.commons.collections.comparators.TransformingComparator; - - /** - * Provides convenient static utility methods for Comparator - * objects.

+ * Provides convenient static utility methods for Comparator + * objects. + *

+ * Most of the utility in this class can also be found in the + * comparators package. This class merely provides a + * convenient central place if you have use for more than one class + * in the comparators subpackage. + *

+ * Note that every method in this class allows you to specify + * null instead of a comparator, in which case + * {@link #NATURAL} will be used. * - * Most of the utility in this class can also be found in the - * comparators package; this class merely provides a - * convenient central place if you have use for more than one class - * in the comparators subpackage.

- * - * Note that every method in this class allows you to specify - * null instead of a comparator, in which case - * {@link #NATURAL} will be used. - * - * @author Paul Jack - * @version $Id$ - * @since 2.1 + * @since 2.1 + * @author Paul Jack + * @author Stephen Colebourne + * @version $Id: $ */ public class ComparatorUtils { - + /** + * Restrictive constructor + */ private ComparatorUtils() { } + /** + * Comparator for natural sort order. + * + * @see ComparableComparator#getInstance + */ + final public static Comparator NATURAL = ComparableComparator.getInstance(); /** - * Comparator for natural sort order. + * Gets a comparator that uses the natural order of the objects. * - * @see ComparableComparator#getInstance + * @return a comparator which uses natural order */ - final public static Comparator NATURAL = - ComparableComparator.getInstance(); - + public static Comparator naturalComparator() { + return NATURAL; + } /** - * Returns a comparator that reverses the order of the given - * comparator. + * Gets a comparator that compares using two {@link Comparator}s. + *

+ * The second comparator is used if the first comparator returns + * that equal. * - * @param comparator the comparator whose order to reverse - * @return a comparator who reverses that order - * @see ReverseComparator + * @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 + * @throws NullPointerException if either comparator is null */ - public static Comparator reverse(Comparator comparator) { - if (comparator == null) comparator = NATURAL; + public static Comparator chainedComparator(Comparator comparator1, Comparator comparator2) { + return chainedComparator(new Comparator[] {comparator1, comparator2}); + } + + /** + * Gets a comparator that compares using an array of {@link Comparator}s. + *

+ * The second comparator is used if the first comparator returns + * that equal and so on. + * + * @param iterators the comparators to use, not null or empty or contain nulls + * @return a combination comparator over the comparators + * @throws NullPointerException if comparators array is null or contains a null + */ + public static Comparator chainedComparator(Comparator[] comparators) { + ComparatorChain chain = new ComparatorChain(); + for (int i = 0; i < comparators.length; i++) { + if (comparators[i] == null) { + throw new NullPointerException("Comparator cannot be null"); + } + chain.addComparator(comparators[i]); + } + return chain; + } + + /** + * Gets a comparator that compares using a collection of {@link Comparator}s. + *

+ * The second comparator is used if the first comparator returns + * that equal and so on. + * + * @param comparators the comparators to use, not null or empty or contain nulls + * @return a combination comparator over the comparators + * @throws NullPointerException if comparators collection is null or contains a null + * @throws ClassCastException if the comparators collection contains the wrong object type + */ + public static Comparator chainedComparator(Collection comparators) { + return chainedComparator( + (Comparator[]) comparators.toArray(new Comparator[comparators.size()]) + ); + } + + /** + * 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 + * @see ReverseComparator + */ + public static Comparator reversedComparator(Comparator comparator) { + if (comparator == null) { + comparator = NATURAL; + } return new ReverseComparator(comparator); } - /** - * Allows the given comparator to compare null values.

+ * Gets a Comparator that controls the comparison of null values. + *

+ * 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.

* - * 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.

- * - * @param comparator the comparator that wants to allow nulls - * @return a version of that comparator that allows nulls - * @see NullComparator + * @param comparator the comparator that wants to allow nulls + * @return a version of that comparator that allows nulls + * @see NullComparator */ - public static Comparator nullLow(Comparator comparator) { - if (comparator == null) comparator = NATURAL; + public static Comparator nullLowComparator(Comparator comparator) { + if (comparator == null) { + comparator = NATURAL; + } return new NullComparator(comparator, false); } - /** - * Allows the given comparator to compare null values.

+ * Gets a Comparator that controls the comparison of null values. + *

+ * 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.

* - * 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.

- * - * @param comparator the comparator that wants to allow nulls - * @return a version of that comparator that allows nulls - * @see NullComparator + * @param comparator the comparator that wants to allow nulls + * @return a version of that comparator that allows nulls + * @see NullComparator */ - public static Comparator nullHigh(Comparator comparator) { - if (comparator == null) comparator = NATURAL; + public static Comparator nullHighComparator(Comparator comparator) { + if (comparator == null) { + comparator = NATURAL; + } return new NullComparator(comparator, true); } - - /** - * Passes transformed objects to the given comparator.

+ * Gets a Comparator that passes transformed objects to the given comparator. + *

+ * Objects passed to the returned comparator will first be transformed + * by the given transformer before they are compared by the given + * comparator. * - * Objects passed to the returned comparator will first be transformed - * by the given transformer before they are compared by the given - * comparator.

- * - * @param comparator the sort order to use - * @param t the transformer to use - * @return a comparator that transforms its input objects before - * comparing them - * @see TransformingComparator + * @param comparator the sort order to use + * @param transformer the transformer to use + * @return a comparator that transforms its input objects before comparing them + * @see TransformingComparator */ - public static Comparator transform(Comparator comparator, Transformer t) { - if (comparator == null) comparator = NATURAL; - return new TransformingComparator(t, comparator); + public static Comparator transformedComparator(Comparator comparator, Transformer transformer) { + if (comparator == null) { + comparator = NATURAL; + } + return new TransformingComparator(transformer, comparator); } - /** * Returns the smaller of the given objects according to the given * comparator. @@ -173,12 +236,13 @@ public class ComparatorUtils { * @return the smaller of the two objects */ public static Object min(Object o1, Object o2, Comparator comparator) { - if (comparator == null) comparator = NATURAL; + if (comparator == null) { + comparator = NATURAL; + } int c = comparator.compare(o1, o2); - return (c < 0) ? o1 : o2; + return (c < 0) ? o1 : o2; } - /** * Returns the smaller of the given objects according to the given * comparator. @@ -189,8 +253,10 @@ public class ComparatorUtils { * @return the smaller of the two objects */ public static Object max(Object o1, Object o2, Comparator comparator) { - if (comparator == null) comparator = NATURAL; + if (comparator == null) { + comparator = NATURAL; + } int c = comparator.compare(o1, o2); - return (c > 0) ? o1 : o2; + return (c > 0) ? o1 : o2; } }