From 2e30bec7af9ab1ba7fdccd92a2ccf209fba19f32 Mon Sep 17 00:00:00 2001 From: Henri Yandell Date: Thu, 25 Aug 2011 15:27:39 +0000 Subject: [PATCH] Rolling back r1161378. NullComparator and ReverseComparator need the NATURAL_COMPARATOR field and the ComparableComparator.INSTANCE field is not a straight replacement git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@1161605 13f79535-47bb-0310-9956-ffa450edef68 --- .../lang3/compare/ComparatorUtils.java | 201 ++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 src/main/java/org/apache/commons/lang3/compare/ComparatorUtils.java diff --git a/src/main/java/org/apache/commons/lang3/compare/ComparatorUtils.java b/src/main/java/org/apache/commons/lang3/compare/ComparatorUtils.java new file mode 100644 index 000000000..eb2aadc6c --- /dev/null +++ b/src/main/java/org/apache/commons/lang3/compare/ComparatorUtils.java @@ -0,0 +1,201 @@ +/* + * 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.lang3.compare; + +import java.util.Collection; +import java.util.Comparator; + +/** + * 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 Commons Collections 2.1 + * @version $Revision$ $Date$ + */ +public class ComparatorUtils { + + /** + * ComparatorUtils should not normally be instantiated. + */ + public ComparatorUtils() { + } + + /** + * Comparator for natural sort order. + * + * @see ComparableComparator#getInstance + */ + @SuppressWarnings("unchecked") + public static final Comparator NATURAL_COMPARATOR = ComparableComparator.comparableComparator(); + + /** + * Gets a comparator that uses the natural order of the objects. + * + * @return a comparator which uses natural order + */ + @SuppressWarnings("unchecked") + public static > Comparator naturalComparator() { + return NATURAL_COMPARATOR; + } + + /** + * Gets a comparator that compares using two {@link Comparator}s. + *

+ * 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 + */ + @SuppressWarnings("unchecked") + 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 + */ + @SuppressWarnings("unchecked") + 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) { + return new ReverseComparator(comparator); + } + + /** + * 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 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 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); + } + + /** + * 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 + */ + @SuppressWarnings("unchecked") + public static E min(E o1, E 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 + */ + @SuppressWarnings("unchecked") + public static E max(E o1, E o2, Comparator comparator) { + if (comparator == null) { + comparator = NATURAL_COMPARATOR; + } + int c = comparator.compare(o1, o2); + return (c > 0) ? o1 : o2; + } + +}