1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections4;
18
19 import java.util.Collection;
20 import java.util.Comparator;
21 import java.util.Objects;
22
23 import org.apache.commons.collections4.comparators.BooleanComparator;
24 import org.apache.commons.collections4.comparators.ComparableComparator;
25 import org.apache.commons.collections4.comparators.ComparatorChain;
26 import org.apache.commons.collections4.comparators.NullComparator;
27 import org.apache.commons.collections4.comparators.ReverseComparator;
28 import org.apache.commons.collections4.comparators.TransformingComparator;
29
30 /**
31 * Provides convenient static utility methods for <Code>Comparator</Code>
32 * objects.
33 * <p>
34 * Most of the functionality in this class can also be found in the
35 * {@code comparators} package. This class merely provides a
36 * convenient central place if you have use for more than one class
37 * in the {@code comparators} subpackage.
38 * </p>
39 *
40 * @since 2.1
41 */
42 public class ComparatorUtils {
43
44 @SuppressWarnings("rawtypes")
45 private static final Comparator[] EMPTY_COMPARATOR_ARRAY = {};
46
47 /**
48 * Comparator for natural sort order.
49 *
50 * @see ComparableComparator#comparableComparator()
51 */
52 @SuppressWarnings({ "rawtypes", "unchecked" }) // explicit type needed for Java 1.5 compilation
53 public static final Comparator NATURAL_COMPARATOR = ComparableComparator.<Comparable>comparableComparator();
54
55 /**
56 * Gets a Comparator that can sort Boolean objects.
57 * <p>
58 * The parameter specifies whether true or false is sorted first.
59 * </p>
60 * <p>
61 * The comparator throws NullPointerException if a null value is compared.
62 * </p>
63 *
64 * @param trueFirst when {@code true}, sort
65 * {@code true} {@link Boolean}s before
66 * {@code false} {@link Boolean}s.
67 * @return a comparator that sorts booleans
68 */
69 public static Comparator<Boolean> booleanComparator(final boolean trueFirst) {
70 return BooleanComparator.booleanComparator(trueFirst);
71 }
72
73 /**
74 * Gets a comparator that compares using a collection of {@link Comparator}s,
75 * applied in (default iterator) sequence until one returns not equal or the
76 * collection is exhausted.
77 *
78 * @param <E> the object type to compare
79 * @param comparators the comparators to use, not null or empty or containing nulls
80 * @return a {@link ComparatorChain} formed from the input comparators
81 * @throws NullPointerException if comparators collection is null or contains a null
82 * @throws ClassCastException if the comparators collection contains the wrong object type
83 * @see ComparatorChain
84 */
85 @SuppressWarnings("unchecked")
86 public static <E> Comparator<E> chainedComparator(final Collection<Comparator<E>> comparators) {
87 return chainedComparator(comparators.toArray(EMPTY_COMPARATOR_ARRAY));
88 }
89
90 /**
91 * Gets a comparator that compares using an array of {@link Comparator}s, applied
92 * in sequence until one returns not equal or the array is exhausted.
93 *
94 * @param <E> the object type to compare
95 * @param comparators the comparators to use, not null or empty or containing nulls
96 * @return a {@link ComparatorChain} formed from the input comparators
97 * @throws NullPointerException if comparators array is null or contains a null
98 * @see ComparatorChain
99 */
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
243 }