001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections4;
018
019import java.util.Collection;
020import java.util.Comparator;
021import java.util.Objects;
022
023import org.apache.commons.collections4.comparators.BooleanComparator;
024import org.apache.commons.collections4.comparators.ComparableComparator;
025import org.apache.commons.collections4.comparators.ComparatorChain;
026import org.apache.commons.collections4.comparators.NullComparator;
027import org.apache.commons.collections4.comparators.ReverseComparator;
028import org.apache.commons.collections4.comparators.TransformingComparator;
029
030/**
031 * Provides convenient static utility methods for <Code>Comparator</Code>
032 * objects.
033 * <p>
034 * Most of the functionality in this class can also be found in the
035 * {@code comparators} package. This class merely provides a
036 * convenient central place if you have use for more than one class
037 * in the {@code comparators} subpackage.
038 * </p>
039 *
040 * @since 2.1
041 */
042public class ComparatorUtils {
043
044    @SuppressWarnings("rawtypes")
045    private static final Comparator[] EMPTY_COMPARATOR_ARRAY = {};
046
047    /**
048     * Comparator for natural sort order.
049     *
050     * @see ComparableComparator#comparableComparator()
051     */
052    @SuppressWarnings({ "rawtypes", "unchecked" }) // explicit type needed for Java 1.5 compilation
053    public static final Comparator NATURAL_COMPARATOR = ComparableComparator.<Comparable>comparableComparator();
054
055    /**
056     * Gets a Comparator that can sort Boolean objects.
057     * <p>
058     * The parameter specifies whether true or false is sorted first.
059     * </p>
060     * <p>
061     * The comparator throws NullPointerException if a null value is compared.
062     * </p>
063     *
064     * @param trueFirst  when {@code true}, sort
065     *        {@code true} {@link Boolean}s before
066     *        {@code false} {@link Boolean}s.
067     * @return  a comparator that sorts booleans
068     */
069    public static Comparator<Boolean> booleanComparator(final boolean trueFirst) {
070        return BooleanComparator.booleanComparator(trueFirst);
071    }
072
073    /**
074     * Gets a comparator that compares using a collection of {@link Comparator}s,
075     * applied in (default iterator) sequence until one returns not equal or the
076     * collection is exhausted.
077     *
078     * @param <E>  the object type to compare
079     * @param comparators  the comparators to use, not null or empty or containing nulls
080     * @return a {@link ComparatorChain} formed from the input comparators
081     * @throws NullPointerException if comparators collection is null or contains a null
082     * @throws ClassCastException if the comparators collection contains the wrong object type
083     * @see ComparatorChain
084     */
085    @SuppressWarnings("unchecked")
086    public static <E> Comparator<E> chainedComparator(final Collection<Comparator<E>> comparators) {
087        return chainedComparator(comparators.toArray(EMPTY_COMPARATOR_ARRAY));
088    }
089
090    /**
091     * Gets a comparator that compares using an array of {@link Comparator}s, applied
092     * in sequence until one returns not equal or the array is exhausted.
093     *
094     * @param <E>  the object type to compare
095     * @param comparators  the comparators to use, not null or empty or containing nulls
096     * @return a {@link ComparatorChain} formed from the input comparators
097     * @throws NullPointerException if comparators array is null or contains a null
098     * @see ComparatorChain
099     */
100    public static <E> Comparator<E> chainedComparator(final Comparator<E>... comparators) {
101        final ComparatorChain<E> chain = new ComparatorChain<>();
102        for (final Comparator<E> comparator : comparators) {
103            chain.addComparator(Objects.requireNonNull(comparator, "comparator"));
104        }
105        return chain;
106    }
107
108    /**
109     * Returns the largest of the given objects according to the given
110     * comparator, returning the second object if the comparator
111     * returns equal.
112     *
113     * @param <E>  the object type to compare
114     * @param o1  the first object to compare
115     * @param o2  the second object to compare
116     * @param comparator  the sort order to use
117     * @return  the larger of the two objects
118     */
119    @SuppressWarnings("unchecked")
120    public static <E> E max(final E o1, final E o2, Comparator<E> comparator) {
121        if (comparator == null) {
122            comparator = NATURAL_COMPARATOR;
123        }
124        final int c = comparator.compare(o1, o2);
125        return c > 0 ? o1 : o2;
126    }
127
128    /**
129     * Returns the smallest of the given objects according to the given
130     * comparator, returning the second object if the comparator
131     * returns equal.
132     *
133     * @param <E>  the object type to compare
134     * @param o1  the first object to compare
135     * @param o2  the second object to compare
136     * @param comparator  the sort order to use
137     * @return  the smaller of the two objects
138     */
139    @SuppressWarnings("unchecked")
140    public static <E> E min(final E o1, final E o2, Comparator<E> comparator) {
141        if (comparator == null) {
142            comparator = NATURAL_COMPARATOR;
143        }
144        final int c = comparator.compare(o1, o2);
145        return c < 0 ? o1 : o2;
146    }
147
148    /**
149     * Gets a comparator that uses the natural order of the objects.
150     *
151     * @param <E>  the object type to compare
152     * @return  a comparator which uses natural order
153     */
154    @SuppressWarnings("unchecked")
155    public static <E extends Comparable<? super E>> Comparator<E> naturalComparator() {
156        return NATURAL_COMPARATOR;
157    }
158
159    /**
160     * Gets a Comparator that controls the comparison of {@code null} values.
161     * <p>
162     * The returned comparator will consider a null value to be greater than
163     * any nonnull value, and equal to any other null value.  Two nonnull
164     * values will be evaluated with the given comparator.
165     * </p>
166     *
167     * @param <E>  the object type to compare
168     * @param comparator the comparator that wants to allow nulls
169     * @return  a version of that comparator that allows nulls
170     * @see NullComparator
171     */
172    @SuppressWarnings("unchecked")
173    public static <E> Comparator<E> nullHighComparator(Comparator<E> comparator) {
174        if (comparator == null) {
175            comparator = NATURAL_COMPARATOR;
176        }
177        return new NullComparator<>(comparator, true);
178    }
179
180    /**
181     * Gets a Comparator that controls the comparison of {@code null} values.
182     * <p>
183     * The returned comparator will consider a null value to be less than
184     * any nonnull value, and equal to any other null value.  Two nonnull
185     * values will be evaluated with the given comparator.
186     * </p>
187     *
188     * @param <E>  the object type to compare
189     * @param comparator the comparator that wants to allow nulls
190     * @return  a version of that comparator that allows nulls
191     * @see NullComparator
192     */
193    @SuppressWarnings("unchecked")
194    public static <E> Comparator<E> nullLowComparator(Comparator<E> comparator) {
195        if (comparator == null) {
196            comparator = NATURAL_COMPARATOR;
197        }
198        return new NullComparator<>(comparator, false);
199    }
200
201    /**
202     * Gets a comparator that reverses the order of the given comparator.
203     *
204     * @param <E>  the object type to compare
205     * @param comparator  the comparator to reverse
206     * @return  a comparator that reverses the order of the input comparator
207     * @see ReverseComparator
208     */
209    public static <E> Comparator<E> reversedComparator(final Comparator<E> comparator) {
210        return new ReverseComparator<>(comparator);
211    }
212
213    /**
214     * Gets a Comparator that passes transformed objects to the given comparator.
215     * <p>
216     * Objects passed to the returned comparator will first be transformed
217     * by the given transformer before they are compared by the given
218     * comparator.
219     * </p>
220     *
221     * @param <I>  the input object type of the transformed comparator
222     * @param <O>  the object type of the decorated comparator
223     * @param comparator  the sort order to use
224     * @param transformer  the transformer to use
225     * @return  a comparator that transforms its input objects before comparing them
226     * @see  TransformingComparator
227     */
228    @SuppressWarnings("unchecked")
229    public static <I, O> Comparator<I> transformedComparator(Comparator<O> comparator,
230            final Transformer<? super I, ? extends O> transformer) {
231
232        if (comparator == null) {
233            comparator = NATURAL_COMPARATOR;
234        }
235        return new TransformingComparator<>(transformer, comparator);
236    }
237
238    /**
239     * Don't allow instances.
240     */
241    private ComparatorUtils() {
242        // empty
243    }
244
245}