org.apache.commons.collections4.ComparatorUtils Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You 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.collections4;
import java.util.Collection;
import java.util.Comparator;
import org.apache.commons.collections4.comparators.BooleanComparator;
import org.apache.commons.collections4.comparators.ComparableComparator;
import org.apache.commons.collections4.comparators.ComparatorChain;
import org.apache.commons.collections4.comparators.NullComparator;
import org.apache.commons.collections4.comparators.ReverseComparator;
import org.apache.commons.collections4.comparators.TransformingComparator;
/**
* Provides convenient static utility methods for Comparator
* objects.
*
* Most of the functionality 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.
*
* @since 2.1
*/
public class ComparatorUtils {
/**
* ComparatorUtils should not normally be instantiated.
*/
private ComparatorUtils() {}
/**
* Comparator for natural sort order.
*
* @see ComparableComparator#comparableComparator()
*/
@SuppressWarnings({ "rawtypes", "unchecked" }) // explicit type needed for Java 1.5 compilation
public static final Comparator NATURAL_COMPARATOR = ComparableComparator.comparableComparator();
/**
* Gets a comparator that uses the natural order of the objects.
*
* @param the object type to compare
* @return a comparator which uses natural order
*/
@SuppressWarnings("unchecked")
public static > Comparator naturalComparator() {
return NATURAL_COMPARATOR;
}
/**
* 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 the object type to compare
* @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(final Comparator... comparators) {
final ComparatorChain chain = new ComparatorChain<>();
for (final Comparator comparator : comparators) {
if (comparator == null) {
throw new NullPointerException("Comparator cannot be null");
}
chain.addComparator(comparator);
}
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 the object type to compare
* @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
*/
@SuppressWarnings("unchecked")
public static Comparator chainedComparator(final Collection> comparators) {
return chainedComparator(
(Comparator[]) comparators.toArray(new Comparator[comparators.size()])
);
}
/**
* Gets a comparator that reverses the order of the given comparator.
*
* @param the object type to compare
* @param comparator the comparator to reverse
* @return a comparator that reverses the order of the input comparator
* @see ReverseComparator
*/
public static Comparator reversedComparator(final Comparator comparator) {
return new ReverseComparator<>(comparator);
}
/**
* Gets a Comparator that can sort Boolean objects.
*
* The parameter specifies whether true or false is sorted first.
*
* The comparator throws NullPointerException if a null value is compared.
*
* @param trueFirst when true, sort
* true {@link Boolean}s before
* false {@link Boolean}s.
* @return a comparator that sorts booleans
*/
public static Comparator booleanComparator(final boolean trueFirst) {
return BooleanComparator.booleanComparator(trueFirst);
}
/**
* 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.
*
* @param the object type to compare
* @param comparator the comparator that wants to allow nulls
* @return a version of that comparator that allows nulls
* @see NullComparator
*/
@SuppressWarnings("unchecked")
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 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.
*
* @param the object type to compare
* @param comparator the comparator that wants to allow nulls
* @return a version of that comparator that allows nulls
* @see NullComparator
*/
@SuppressWarnings("unchecked")
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.
*
* Objects passed to the returned comparator will first be transformed
* by the given transformer before they are compared by the given
* comparator.
*
* @param the input object type of the transformed comparator
* @param the object type of the decorated 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
*/
@SuppressWarnings("unchecked")
public static Comparator transformedComparator(Comparator comparator,
final 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 the object type to compare
* @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
*/
@SuppressWarnings("unchecked")
public static E min(final E o1, final E o2, Comparator comparator) {
if (comparator == null) {
comparator = NATURAL_COMPARATOR;
}
final 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 the object type to compare
* @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
*/
@SuppressWarnings("unchecked")
public static E max(final E o1, final E o2, Comparator comparator) {
if (comparator == null) {
comparator = NATURAL_COMPARATOR;
}
final int c = comparator.compare(o1, o2);
return c > 0 ? o1 : o2;
}
}