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 */ 017 package org.apache.commons.collections; 018 019 import java.util.Collection; 020 import java.util.Comparator; 021 022 import org.apache.commons.collections.comparators.BooleanComparator; 023 import org.apache.commons.collections.comparators.ComparableComparator; 024 import org.apache.commons.collections.comparators.ComparatorChain; 025 import org.apache.commons.collections.comparators.NullComparator; 026 import org.apache.commons.collections.comparators.ReverseComparator; 027 import org.apache.commons.collections.comparators.TransformingComparator; 028 029 /** 030 * Provides convenient static utility methods for <Code>Comparator</Code> 031 * objects. 032 * <p> 033 * Most of the functionality in this class can also be found in the 034 * <code>comparators</code> package. This class merely provides a 035 * convenient central place if you have use for more than one class 036 * in the <code>comparators</code> subpackage. 037 * 038 * @since Commons Collections 2.1 039 * @version $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $ 040 * 041 * @author Paul Jack 042 * @author Stephen Colebourne 043 */ 044 public class ComparatorUtils { 045 046 /** 047 * ComparatorUtils should not normally be instantiated. 048 */ 049 public ComparatorUtils() { 050 } 051 052 /** 053 * Comparator for natural sort order. 054 * 055 * @see ComparableComparator#getInstance 056 */ 057 public static final Comparator NATURAL_COMPARATOR = ComparableComparator.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, Comparator comparator2) { 080 return chainedComparator(new Comparator[] {comparator1, comparator2}); 081 } 082 083 /** 084 * Gets a comparator that compares using an array of {@link Comparator}s, applied 085 * in sequence until one returns not equal or the array is exhausted. 086 * 087 * @param comparators the comparators to use, not null or empty or containing nulls 088 * @return a {@link ComparatorChain} formed from the input comparators 089 * @throws NullPointerException if comparators array is null or contains a null 090 * @see ComparatorChain 091 */ 092 public static Comparator chainedComparator(Comparator[] comparators) { 093 ComparatorChain chain = new ComparatorChain(); 094 for (int i = 0; i < comparators.length; i++) { 095 if (comparators[i] == null) { 096 throw new NullPointerException("Comparator cannot be null"); 097 } 098 chain.addComparator(comparators[i]); 099 } 100 return chain; 101 } 102 103 /** 104 * Gets a comparator that compares using a collection of {@link Comparator}s, 105 * applied in (default iterator) sequence until one returns not equal or the 106 * collection is exhausted. 107 * 108 * @param comparators the comparators to use, not null or empty or containing nulls 109 * @return a {@link ComparatorChain} formed from the input comparators 110 * @throws NullPointerException if comparators collection is null or contains a null 111 * @throws ClassCastException if the comparators collection contains the wrong object type 112 * @see ComparatorChain 113 */ 114 public static Comparator chainedComparator(Collection comparators) { 115 return chainedComparator( 116 (Comparator[]) comparators.toArray(new Comparator[comparators.size()]) 117 ); 118 } 119 120 /** 121 * Gets a comparator that reverses the order of the given comparator. 122 * 123 * @param comparator the comparator to reverse 124 * @return a comparator that reverses the order of the input comparator 125 * @see ReverseComparator 126 */ 127 public static Comparator reversedComparator(Comparator comparator) { 128 if (comparator == null) { 129 comparator = NATURAL_COMPARATOR; 130 } 131 return new ReverseComparator(comparator); 132 } 133 134 /** 135 * Gets a Comparator that can sort Boolean objects. 136 * <p> 137 * The parameter specifies whether true or false is sorted first. 138 * <p> 139 * The comparator throws NullPointerException if a null value is compared. 140 * 141 * @param trueFirst when <code>true</code>, sort 142 * <code>true</code> {@link Boolean}s before 143 * <code>false</code> {@link Boolean}s. 144 * @return a comparator that sorts booleans 145 */ 146 public static Comparator booleanComparator(boolean trueFirst) { 147 return BooleanComparator.getBooleanComparator(trueFirst); 148 } 149 150 /** 151 * Gets a Comparator that controls the comparison of <code>null</code> values. 152 * <p> 153 * The returned comparator will consider a null value to be less than 154 * any nonnull value, and equal to any other null value. Two nonnull 155 * values will be evaluated with the given comparator. 156 * 157 * @param comparator the comparator that wants to allow nulls 158 * @return a version of that comparator that allows nulls 159 * @see NullComparator 160 */ 161 public static Comparator nullLowComparator(Comparator comparator) { 162 if (comparator == null) { 163 comparator = NATURAL_COMPARATOR; 164 } 165 return new NullComparator(comparator, false); 166 } 167 168 /** 169 * Gets a Comparator that controls the comparison of <code>null</code> values. 170 * <p> 171 * The returned comparator will consider a null value to be greater than 172 * any nonnull value, and equal to any other null value. Two nonnull 173 * values will be evaluated with the given comparator. 174 * 175 * @param comparator the comparator that wants to allow nulls 176 * @return a version of that comparator that allows nulls 177 * @see NullComparator 178 */ 179 public static Comparator nullHighComparator(Comparator comparator) { 180 if (comparator == null) { 181 comparator = NATURAL_COMPARATOR; 182 } 183 return new NullComparator(comparator, true); 184 } 185 186 /** 187 * Gets a Comparator that passes transformed objects to the given comparator. 188 * <p> 189 * Objects passed to the returned comparator will first be transformed 190 * by the given transformer before they are compared by the given 191 * comparator. 192 * 193 * @param comparator the sort order to use 194 * @param transformer the transformer to use 195 * @return a comparator that transforms its input objects before comparing them 196 * @see TransformingComparator 197 */ 198 public static Comparator transformedComparator(Comparator comparator, Transformer transformer) { 199 if (comparator == null) { 200 comparator = NATURAL_COMPARATOR; 201 } 202 return new TransformingComparator(transformer, comparator); 203 } 204 205 /** 206 * Returns the smaller of the given objects according to the given 207 * comparator, returning the second object if the comparator 208 * returns equal. 209 * 210 * @param o1 the first object to compare 211 * @param o2 the second object to compare 212 * @param comparator the sort order to use 213 * @return the smaller of the two objects 214 */ 215 public static Object min(Object o1, Object o2, Comparator comparator) { 216 if (comparator == null) { 217 comparator = NATURAL_COMPARATOR; 218 } 219 int c = comparator.compare(o1, o2); 220 return (c < 0) ? o1 : o2; 221 } 222 223 /** 224 * Returns the larger of the given objects according to the given 225 * comparator, returning the second object if the comparator 226 * returns equal. 227 * 228 * @param o1 the first object to compare 229 * @param o2 the second object to compare 230 * @param comparator the sort order to use 231 * @return the larger of the two objects 232 */ 233 public static Object max(Object o1, Object o2, Comparator comparator) { 234 if (comparator == null) { 235 comparator = NATURAL_COMPARATOR; 236 } 237 int c = comparator.compare(o1, o2); 238 return (c > 0) ? o1 : o2; 239 } 240 241 }