/*
* 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: 155406 $ $Date: 2005-02-26 12:55:26 +0000 (Sat, 26 Feb 2005) $
*
* @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;
}
}