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; } }