1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.collections15.comparators;
17
18 import net.sf.collections15.Transformer;
19
20 import java.util.Collection;
21 import java.util.Comparator;
22
23 /***
24 * Provides convenient static utility methods for <Code>Comparator</Code>
25 * objects.
26 * <p/>
27 * Most of the functionality in this class can also be found in the
28 * <code>comparators</code> package. This class merely provides a convenient
29 * central place if you have use for more than one class in the
30 * <code>comparators</code> subpackage.
31 *
32 * @author Paul Jack
33 * @author Stephen Colebourne
34 * @author Chris Lambrou (port to Java 5.0)
35 * @since Collections15 1.0
36 */
37 public class ComparatorUtils
38 {
39
40 /***
41 * Protected constructor prevents direct instantiation, but allows users to
42 * extend this library to provide their own augmented static library class.
43 */
44 protected ComparatorUtils()
45 {
46 }
47
48 /***
49 * Gets a comparator that uses the natural order of the objects.
50 *
51 * @return A comparator which uses the natural ordering of the compared
52 * objects.
53 */
54 public static <T extends Comparable> Comparator<T> naturalComparator()
55 {
56 return ComparableComparator.getInstance();
57 }
58
59 /***
60 * Gets a comparator that compares using a collection of
61 * <code>Comparator</code>s, applied in (default iterator) sequence until
62 * one returns not equal or the collection is exhausted.
63 *
64 * @param comparators The <code>Comparators</code> to use. Cannot be
65 * <code>null</code> or contains any <code>null</code>
66 * elements. May be empty.
67 *
68 * @return A <code>Comparator</code> that chains together the input
69 * <code>Comparator</code>s. When comparing two object, it will
70 * iterate through the chain, comparing the objects using each
71 * comparator in turn, and returning the first non-zero result. If
72 * the chain is exhausted and none of the <code>Comparator</code>s
73 * returns a non-zero value, zero is returned.
74 *
75 * @throws IllegalArgumentException If <code>comparators</code> is
76 * <code>null</code> or contains a
77 * <code>null</code>. It may be empty,
78 * however.
79 */
80 public static <T> Comparator<T> chainedComparator(Collection<Comparator<T>> comparators)
81 {
82 return ComparatorChain.getInstance(comparators);
83 }
84
85 /***
86 * Gets a <code>Comparator</code> whose ordering is based on the reverse of
87 * the natural ordering of the compared objects.
88 *
89 * @return A <code>Comparator</code> whose ordering is based on the reverse
90 * of the natural ordering of the compared objects.
91 *
92 * @see ReverseComparator
93 */
94 public static <T extends Comparable> Comparator<T> reversedComparator()
95 {
96 return ReverseComparator.getInstance();
97 }
98
99 /***
100 * Gets a <code>Comparator</code> that reverses the order of a specified
101 * comparator.
102 *
103 * @param comparator The <code>Comparator</code> for which a reversed
104 * ordering is required.
105 *
106 * @return A <code>Comparator</code> whose ordering is the reverse of the
107 * specified input <code>Comparator</code>.
108 *
109 * @throws IllegalArgumentException Thrown if the specified <code>Comparator</code>
110 * is <code>null</code>.
111 * @see ReverseComparator
112 */
113 public static <T> Comparator<T> reversedComparator(Comparator<T> comparator)
114 {
115 return ReverseComparator.decorate(comparator);
116 }
117
118 /***
119 * Gets a <code>Comparator</code> that can sort <code>Boolean</code>
120 * objects.
121 * <p/>
122 * The parameter specifies whether <code>true</code> or <code>false</code>
123 * is sorted first.
124 * <p/>
125 * The comparator throws <code>NullPointerException</code> if a
126 * <code>null</code> value is compared.
127 *
128 * @param trueFirst when <code>true</code>, sort <code>true Boolean</code>
129 * values before <code>false</code> ones.when
130 * <code>false</code>, sort <code>true Boolean</code>
131 * values after <code>false</code> ones.
132 *
133 * @return A <code>Comparator</code> that sorts <code>Boolean</code>s.
134 */
135 public static Comparator<Boolean> booleanComparator(boolean trueFirst)
136 {
137 return BooleanComparator.getInstance(trueFirst);
138 }
139
140 /***
141 * Gets a Comparator that controls the comparison of <code>null</code>
142 * values.
143 * <p/>
144 * The returned comparator will consider a null value to be less than any
145 * nonnull value, and equal to any other null value. Two nonnull values
146 * will be evaluated with the given comparator.
147 *
148 * @param comparator the comparator that wants to allow nulls
149 *
150 * @return a version of that comparator that allows nulls
151 *
152 * @see NullComparator
153 */
154 public static <T> Comparator<T> nullLowComparator(Comparator<T> comparator)
155 {
156 return new NullComparator<T>(comparator, false);
157 }
158
159 /***
160 * Gets a Comparator that controls the comparison of <code>null</code>
161 * values.
162 * <p/>
163 * The returned comparator will consider a null value to be less than any
164 * nonnull value, and equal to any other null value. Two nonnull values
165 * will be evaluated according to their natural ordering.
166 *
167 * @return a version of that comparator that allows nulls
168 *
169 * @see NullComparator
170 */
171 public static <T extends Comparable> Comparator<T> nullLowComparator()
172 {
173 return NullComparator.getInstance(false);
174 }
175
176 /***
177 * Gets a Comparator that controls the comparison of <code>null</code>
178 * values.
179 * <p/>
180 * The returned comparator will consider a null value to be greater than any
181 * nonnull value, and equal to any other null value. Two nonnull values
182 * will be evaluated with the given comparator.
183 *
184 * @param comparator the comparator that wants to allow nulls
185 *
186 * @return a version of that comparator that allows nulls
187 *
188 * @see NullComparator
189 */
190 public static <T> Comparator<T> nullHighComparator(Comparator<T> comparator)
191 {
192 return new NullComparator<T>(comparator, true);
193 }
194
195 /***
196 * Gets a Comparator that controls the comparison of <code>null</code>
197 * values.
198 * <p/>
199 * The returned comparator will consider a null value to be greater than any
200 * nonnull value, and equal to any other null value. Two nonnull values
201 * will be evaluated according to their natural ordering.
202 *
203 * @return a version of that comparator that allows nulls
204 *
205 * @see NullComparator
206 */
207 public static <T extends Comparable> Comparator<T> nullHighComparator()
208 {
209 return NullComparator.getInstance(true);
210 }
211
212 /***
213 * Gets a Comparator that passes transformed objects to the given
214 * comparator.
215 * <p/>
216 * Objects passed to the returned comparator will first be transformed by
217 * the given transformer before they are compared by the given comparator.
218 *
219 * @param transformer the transformer to use
220 *
221 * @return a comparator that transforms its input objects before comparing
222 * them
223 *
224 * @see TransformingComparator
225 */
226 public static <I, O extends Comparable> Comparator<I> transformedComparator(Transformer<I, O> transformer)
227 {
228 return TransformingComparator.getInstance(transformer);
229 }
230
231 /***
232 * Gets a Comparator that passes transformed objects to the given
233 * comparator.
234 * <p/>
235 * Objects passed to the returned comparator will first be transformed by
236 * the given transformer before they are compared by the given comparator.
237 *
238 * @param comparator the sort order to use
239 * @param transformer the transformer to use
240 *
241 * @return a comparator that transforms its input objects before comparing
242 * them
243 *
244 * @see TransformingComparator
245 */
246 public static <I, O> Comparator<I> transformedComparator(Comparator<O> comparator, Transformer<I, O> transformer)
247 {
248 return TransformingComparator.decorate(transformer, comparator);
249 }
250
251 /***
252 * Returns the smaller of the given objects according to the given
253 * comparator, returning the second object if the comparator returns equal.
254 *
255 * @param o1 the first object to compare
256 * @param o2 the second object to compare
257 * @param comparator the sort order to use
258 *
259 * @return the smaller of the two objects
260 */
261 public static <T> T min(T o1, T o2, Comparator<T> comparator)
262 {
263 int c = comparator.compare(o1, o2);
264 return (c < 0) ? o1 : o2;
265 }
266
267 /***
268 * Returns the smaller of the given objects according to the natural sort
269 * order of the objects, returning the second object if the comparator
270 * returns equal.
271 *
272 * @param o1 the first object to compare
273 * @param o2 the second object to compare
274 *
275 * @return the smaller of the two objects
276 */
277 public static <T extends Comparable> T min(T o1, T o2)
278 {
279 int c = o1.compareTo(o2);
280 return (c < 0) ? o1 : o2;
281 }
282
283 /***
284 * Returns the larger of the given objects according to the given
285 * comparator, returning the second object if the comparator returns equal.
286 *
287 * @param o1 the first object to compare
288 * @param o2 the second object to compare
289 * @param comparator the sort order to use
290 *
291 * @return the larger of the two objects
292 */
293 public static <T> T max(T o1, T o2, Comparator<T> comparator)
294 {
295 int c = comparator.compare(o1, o2);
296 return (c > 0) ? o1 : o2;
297 }
298
299 /***
300 * Returns the larger of the given objects according to the given
301 * comparator, returning the second object if the comparator returns equal.
302 *
303 * @param o1 the first object to compare
304 * @param o2 the second object to compare
305 *
306 * @return the larger of the two objects
307 */
308 public static <T extends Comparable> T max(T o1, T o2)
309 {
310 int c = o1.compareTo(o2);
311 return (c > 0) ? o1 : o2;
312 }
313
314 }