Java tutorial
/* * Copyright 2002-2004 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.collections; import java.util.Collection; import java.util.Comparator; import org.apache.commons.collections.comparators.BooleanComparator; import org.apache.commons.collections.comparators.ComparableComparator; 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 <Code>Comparator</Code> * objects. * <p> * 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. * * @since Commons Collections 2.1 * @version $Revision: $ $Date: $ * * @author Paul Jack * @author Stephen Colebourne */ public class ComparatorUtils { /** * ComparatorUtils should not normally be instantiated. */ public ComparatorUtils() { } /** * Comparator for natural sort order. * * @see ComparableComparator#getInstance */ public static final Comparator NATURAL_COMPARATOR = ComparableComparator.getInstance(); /** * Gets a comparator that uses the natural order of the objects. * * @return a comparator which uses natural order */ public static Comparator naturalComparator() { return NATURAL_COMPARATOR; } /** * Gets a comparator that compares using two {@link Comparator}s. * <p> * 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 {@link 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 {@link 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 containing nulls * @return a {@link 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(); 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, * 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 containing nulls * @return a {@link 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((Comparator[]) comparators.toArray(new Comparator[comparators.size()])); } /** * Gets a comparator that reverses the order of the given comparator. * * @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) { if (comparator == null) { comparator = NATURAL_COMPARATOR; } return new ReverseComparator(comparator); } /** * Gets a Comparator that can sort Boolean objects. * <p> * The parameter specifies whether true or false is sorted first. * <p> * The comparator throws NullPointerException if a null value is compared. * * @param trueFirst when <code>true</code>, sort * <code>true</code> {@link Boolean}s before * <code>false</code> {@link Boolean}s. * @return a comparator that sorts booleans */ public static Comparator booleanComparator(boolean trueFirst) { return BooleanComparator.getBooleanComparator(trueFirst); } /** * Gets a Comparator that controls the comparison of <code>null</code> values. * <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. * * @param comparator the comparator that wants to allow nulls * @return a version of that comparator that allows nulls * @see NullComparator */ public static Comparator nullLowComparator(Comparator comparator) { if (comparator == null) { comparator = NATURAL_COMPARATOR; } return new NullComparator(comparator, false); } /** * Gets a Comparator that controls the comparison of <code>null</code> values. * <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. * * @param comparator the comparator that wants to allow nulls * @return a version of that comparator that allows nulls * @see NullComparator */ public static Comparator nullHighComparator(Comparator comparator) { if (comparator == null) { comparator = NATURAL_COMPARATOR; } return new NullComparator(comparator, true); } /** * Gets a Comparator that passes transformed objects to the given comparator. * <p> * 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 transformer the transformer to use * @return a comparator that transforms its input objects before comparing them * @see TransformingComparator */ public static Comparator transformedComparator(Comparator comparator, Transformer transformer) { if (comparator == null) { comparator = NATURAL_COMPARATOR; } return new TransformingComparator(transformer, comparator); } /** * Returns the smaller 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 */ public static Object min(Object o1, Object o2, Comparator comparator) { if (comparator == null) { comparator = NATURAL_COMPARATOR; } int c = comparator.compare(o1, o2); return (c < 0) ? o1 : o2; } /** * 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 larger of the two objects */ public static Object max(Object o1, Object o2, Comparator comparator) { if (comparator == null) { comparator = NATURAL_COMPARATOR; } int c = comparator.compare(o1, o2); return (c > 0) ? o1 : o2; } }