22 * or visit www.oracle.com if you need additional information or have any |
22 * or visit www.oracle.com if you need additional information or have any |
23 * questions. |
23 * questions. |
24 */ |
24 */ |
25 |
25 |
26 package java.util; |
26 package java.util; |
|
27 |
|
28 import java.util.function.Function; |
|
29 import java.util.function.ToIntFunction; |
|
30 import java.util.function.ToLongFunction; |
|
31 import java.util.function.ToDoubleFunction; |
27 |
32 |
28 /** |
33 /** |
29 * A comparison function, which imposes a <i>total ordering</i> on some |
34 * A comparison function, which imposes a <i>total ordering</i> on some |
30 * collection of objects. Comparators can be passed to a sort method (such |
35 * collection of objects. Comparators can be passed to a sort method (such |
31 * as {@link Collections#sort(List,Comparator) Collections.sort} or {@link |
36 * as {@link Collections#sort(List,Comparator) Collections.sort} or {@link |
163 * comparator. |
168 * comparator. |
164 * @see Object#equals(Object) |
169 * @see Object#equals(Object) |
165 * @see Object#hashCode() |
170 * @see Object#hashCode() |
166 */ |
171 */ |
167 boolean equals(Object obj); |
172 boolean equals(Object obj); |
|
173 |
|
174 /** |
|
175 * Returns a comparator that imposes the reverse ordering of this |
|
176 * comparator. |
|
177 * |
|
178 * @return A comparator that imposes the reverse ordering of this |
|
179 * comparator. |
|
180 * @since 1.8 |
|
181 */ |
|
182 default Comparator<T> reverseOrder() { |
|
183 return Collections.reverseOrder(this); |
|
184 } |
|
185 |
|
186 /** |
|
187 * Constructs a lexicographic order comparator with another comparator. |
|
188 * For example, a {@code Comparator<Person> byLastName} can be composed |
|
189 * with another {@code Comparator<Person> byFirstName}, then {@code |
|
190 * byLastName.thenComparing(byFirstName)} creates a {@code |
|
191 * Comparator<Person>} which sorts by last name, and for equal last names |
|
192 * sorts by first name. |
|
193 * |
|
194 * @param other the other comparator used when equals on this. |
|
195 * @throws NullPointerException if the argument is null. |
|
196 * @since 1.8 |
|
197 */ |
|
198 default Comparator<T> thenComparing(Comparator<? super T> other) { |
|
199 return Comparators.compose(this, other); |
|
200 } |
|
201 |
|
202 /** |
|
203 * Constructs a lexicographic order comparator with a function that |
|
204 * extracts a {@code Comparable} key. This default implementation calls |
|
205 * {@code thenComparing(this, Comparators.comparing(keyExtractor))}. |
|
206 * |
|
207 * @param <U> the {@link Comparable} type for comparison |
|
208 * @param keyExtractor the function used to extract the {@link Comparable} sort key |
|
209 * @throws NullPointerException if the argument is null. |
|
210 * @see Comparators#comparing(Function) |
|
211 * @see #thenComparing(Comparator) |
|
212 * @since 1.8 |
|
213 */ |
|
214 default <U extends Comparable<? super U>> Comparator<T> thenComparing(Function<? super T, ? extends U> keyExtractor) { |
|
215 return thenComparing(Comparators.comparing(keyExtractor)); |
|
216 } |
|
217 |
|
218 /** |
|
219 * Constructs a lexicographic order comparator with a function that |
|
220 * extracts a {@code int} value. This default implementation calls {@code |
|
221 * thenComparing(this, Comparators.comparing(keyExtractor))}. |
|
222 * |
|
223 * @param keyExtractor the function used to extract the integer value |
|
224 * @throws NullPointerException if the argument is null. |
|
225 * @see Comparators#comparing(ToIntFunction) |
|
226 * @see #thenComparing(Comparator) |
|
227 * @since 1.8 |
|
228 */ |
|
229 default Comparator<T> thenComparing(ToIntFunction<? super T> keyExtractor) { |
|
230 return thenComparing(Comparators.comparing(keyExtractor)); |
|
231 } |
|
232 |
|
233 /** |
|
234 * Constructs a lexicographic order comparator with a function that |
|
235 * extracts a {@code long} value. This default implementation calls |
|
236 * {@code thenComparing(this, Comparators.comparing(keyExtractor))}. |
|
237 * |
|
238 * @param keyExtractor the function used to extract the long value |
|
239 * @throws NullPointerException if the argument is null. |
|
240 * @see Comparators#comparing(ToLongFunction) |
|
241 * @see #thenComparing(Comparator) |
|
242 * @since 1.8 |
|
243 */ |
|
244 default Comparator<T> thenComparing(ToLongFunction<? super T> keyExtractor) { |
|
245 return thenComparing(Comparators.comparing(keyExtractor)); |
|
246 } |
|
247 |
|
248 /** |
|
249 * Constructs a lexicographic order comparator with a function that |
|
250 * extracts a {@code double} value. This default implementation calls |
|
251 * {@code thenComparing(this, Comparators.comparing(keyExtractor))}. |
|
252 * |
|
253 * @param keyExtractor the function used to extract the double value |
|
254 * @throws NullPointerException if the argument is null. |
|
255 * @see Comparators#comparing(ToDoubleFunction) |
|
256 * @see #thenComparing(Comparator) |
|
257 * @since 1.8 |
|
258 */ |
|
259 default Comparator<T> thenComparing(ToDoubleFunction<? super T> keyExtractor) { |
|
260 return thenComparing(Comparators.comparing(keyExtractor)); |
|
261 } |
168 } |
262 } |