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