@GwtCompatible public abstract class Ordering<T> extends Object implements Comparator<T>
if (Ordering.from(comparator).reverse().isOrdered(list)) { ... }
The from(Comparator)
method returns the equivalent Ordering
instance for a pre-existing comparator. You can also skip the comparator step
and extend Ordering
directly: Ordering<String> byLengthOrdering = new Ordering<String>() {
public int compare(String left, String right) {
return Ints.compare(left.length(), right.length());
}
};
Except as noted, the orderings returned by the factory methods of this
class are serializable if and only if the provided instances that back them
are. For example, if ordering
and function
can themselves be
serialized, then ordering.onResultOf(function)
can as well.Modifier | Constructor and Description |
---|---|
protected |
Ordering()
Constructs a new instance of this class (only invokable by the subclass
constructor, typically implicit).
|
Modifier and Type | Method and Description |
---|---|
static Ordering<Object> |
arbitrary()
Returns an arbitrary ordering over all objects, for which
compare(a,
b) == 0 implies a == b (identity equality). |
int |
binarySearch(List<? extends T> sortedList,
T key)
|
abstract int |
compare(T left,
T right) |
<U extends T> |
compound(Comparator<? super U> secondaryComparator)
Returns an ordering which first uses the ordering
this , but which
in the event of a "tie", then delegates to secondaryComparator . |
static <T> Ordering<T> |
compound(Iterable<? extends Comparator<? super T>> comparators)
Returns an ordering which tries each given comparator in order until a
non-zero result is found, returning that result, and returning zero only if
all comparators return zero.
|
static <T> Ordering<T> |
explicit(List<T> valuesInOrder)
Returns an ordering that compares objects according to the order in
which they appear in the given list.
|
static <T> Ordering<T> |
explicit(T leastValue,
T... remainingValuesInOrder)
Returns an ordering that compares objects according to the order in
which they are given to this method.
|
static <T> Ordering<T> |
from(Comparator<T> comparator)
Returns an ordering for a pre-existing
comparator . |
static <T> Ordering<T> |
from(Ordering<T> ordering)
Deprecated.
no need to use this
|
<E extends T> |
greatestOf(Iterable<E> iterable,
int k)
Returns the
k greatest elements of the given iterable according to
this ordering, in order from greatest to least. |
<E extends T> |
immutableSortedCopy(Iterable<E> iterable)
Returns an immutable copy of the given iterable sorted by this
ordering.
|
boolean |
isOrdered(Iterable<? extends T> iterable)
Returns
true if each element in iterable after the first is
greater than or equal to the element that preceded it, according to this
ordering. |
boolean |
isStrictlyOrdered(Iterable<? extends T> iterable)
Returns
true if each element in iterable after the first is
strictly greater than the element that preceded it, according to
this ordering. |
<E extends T> |
leastOf(Iterable<E> iterable,
int k)
Returns the
k least elements of the given iterable according to
this ordering, in order from least to greatest. |
<S extends T> |
lexicographical()
Returns a new ordering which sorts iterables by comparing corresponding
elements pairwise until a nonzero result is found; imposes "dictionary
order".
|
<E extends T> |
max(E a,
E b)
Returns the greater of the two values according to this ordering.
|
<E extends T> |
max(E a,
E b,
E c,
E... rest)
Returns the greatest of the specified values according to this ordering.
|
<E extends T> |
max(Iterable<E> iterable)
Returns the greatest of the specified values according to this ordering.
|
<E extends T> |
max(Iterator<E> iterator)
Returns the greatest of the specified values according to this ordering.
|
<E extends T> |
min(E a,
E b)
Returns the lesser of the two values according to this ordering.
|
<E extends T> |
min(E a,
E b,
E c,
E... rest)
Returns the least of the specified values according to this ordering.
|
<E extends T> |
min(Iterable<E> iterable)
Returns the least of the specified values according to this ordering.
|
<E extends T> |
min(Iterator<E> iterator)
Returns the least of the specified values according to this ordering.
|
static <C extends Comparable> |
natural()
Returns a serializable ordering that uses the natural order of the values.
|
<S extends T> |
nullsFirst()
Returns an ordering that treats
null as less than all other values
and uses this to compare non-null values. |
<S extends T> |
nullsLast()
Returns an ordering that treats
null as greater than all other
values and uses this ordering to compare non-null values. |
<F> Ordering<F> |
onResultOf(Function<F,? extends T> function)
Returns a new ordering on
F which orders elements by first applying
a function to them, then comparing those results using this . |
<S extends T> |
reverse()
Returns the reverse of this ordering; the
Ordering equivalent to
Collections.reverseOrder(Comparator) . |
<E extends T> |
sortedCopy(Iterable<E> iterable)
Returns a copy of the given iterable sorted by this ordering.
|
static Ordering<Object> |
usingToString()
Returns an ordering that compares objects by the natural ordering of their
string representations as returned by
toString() . |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
equals
protected Ordering()
@GwtCompatible(serializable=true) public static <C extends Comparable> Ordering<C> natural()
NullPointerException
when passed a null
parameter.
The type specification is <C extends Comparable>
, instead of
the technically correct <C extends Comparable<? super C>>
, to
support legacy types from before Java 5.
@GwtCompatible(serializable=true) public static <T> Ordering<T> from(Comparator<T> comparator)
comparator
. Note
that if the comparator is not pre-existing, and you don't require
serialization, you can subclass Ordering
and implement its
compare
method instead.comparator
- the comparator that defines the order@GwtCompatible(serializable=true) @Deprecated public static <T> Ordering<T> from(Ordering<T> ordering)
@GwtCompatible(serializable=true) public static <T> Ordering<T> explicit(List<T> valuesInOrder)
Object.equals(java.lang.Object)
) may be compared. This comparator
imposes a "partial ordering" over the type T
. Subsequent changes
to the valuesInOrder
list will have no effect on the returned
comparator. Null values in the list are not supported.
The returned comparator throws an ClassCastException
when it
receives an input parameter that isn't among the provided values.
The generated comparator is serializable if all the provided values are serializable.
valuesInOrder
- the values that the returned comparator will be able
to compare, in the order the comparator should induceNullPointerException
- if any of the provided values is nullIllegalArgumentException
- if valuesInOrder
contains any
duplicate values (according to Object.equals(java.lang.Object)
)@GwtCompatible(serializable=true) public static <T> Ordering<T> explicit(T leastValue, T... remainingValuesInOrder)
Object.equals(java.lang.Object)
) may be compared. This comparator
imposes a "partial ordering" over the type T
. Null values in the
argument list are not supported.
The returned comparator throws a ClassCastException
when it
receives an input parameter that isn't among the provided values.
The generated comparator is serializable if all the provided values are serializable.
leastValue
- the value which the returned comparator should consider
the "least" of all valuesremainingValuesInOrder
- the rest of the values that the returned
comparator will be able to compare, in the order the comparator should
followNullPointerException
- if any of the provided values is nullIllegalArgumentException
- if any duplicate values (according to
Object.equals(Object)
) are present among the method argumentspublic static Ordering<Object> arbitrary()
compare(a,
b) == 0
implies a == b
(identity equality). There is no meaning
whatsoever to the order imposed, but it is constant for the life of the VM.
Because the ordering is identity-based, it is not "consistent with
Object.equals(Object)
" as defined by Comparator
. Use
caution when building a SortedSet
or SortedMap
from it, as
the resulting collection will not behave exactly according to spec.
This ordering is not serializable, as its implementation relies on
System.identityHashCode(Object)
, so its behavior cannot be
preserved across serialization.
@GwtCompatible(serializable=true) public static Ordering<Object> usingToString()
toString()
. It does not
support null values.
The comparator is serializable.
@GwtCompatible(serializable=true) public static <T> Ordering<T> compound(Iterable<? extends Comparator<? super T>> comparators)
comparators
iterable at the time it was provided to this
method.
The returned ordering is equivalent to that produced using Ordering.from(comp1).compound(comp2).compound(comp3) . . .
.
Warning: Supplying an argument with undefined iteration order,
such as a HashSet
, will produce non-deterministic results.
comparators
- the comparators to try in order@GwtCompatible(serializable=true) public <U extends T> Ordering<U> compound(Comparator<? super U> secondaryComparator)
this
, but which
in the event of a "tie", then delegates to secondaryComparator
.
For example, to sort a bug list first by status and second by priority, you
might use byStatus.compound(byPriority)
. For a compound ordering
with three or more components, simply chain multiple calls to this method.
An ordering produced by this method, or a chain of calls to this method,
is equivalent to one created using compound(Iterable)
on
the same component comparators.
@GwtCompatible(serializable=true) public <S extends T> Ordering<S> reverse()
Ordering
equivalent to
Collections.reverseOrder(Comparator)
.@GwtCompatible(serializable=true) public <F> Ordering<F> onResultOf(Function<F,? extends T> function)
F
which orders elements by first applying
a function to them, then comparing those results using this
. For
example, to compare objects by their string forms, in a case-insensitive
manner, use: Ordering.from(String.CASE_INSENSITIVE_ORDER)
.onResultOf(Functions.toStringFunction())
@GwtCompatible(serializable=true) public <S extends T> Ordering<Iterable<S>> lexicographical()
[] < [1] < [1, 1] < [1, 2] < [2]
.
Note that ordering.lexicographical().reverse()
is not
equivalent to ordering.reverse().lexicographical()
(consider how
each would order [1]
and [1, 1]
).
@GwtCompatible(serializable=true) public <S extends T> Ordering<S> nullsFirst()
null
as less than all other values
and uses this
to compare non-null values.@GwtCompatible(serializable=true) public <S extends T> Ordering<S> nullsLast()
null
as greater than all other
values and uses this ordering to compare non-null values.public abstract int compare(@Nullable T left, @Nullable T right)
compare
in interface Comparator<T>
@Beta public <E extends T> List<E> leastOf(Iterable<E> iterable, int k)
k
least elements of the given iterable according to
this ordering, in order from least to greatest. If there are fewer than
k
elements present, all will be included.
The implementation does not necessarily use a stable sorting algorithm; when multiple elements are equivalent, it is undefined which will come first.
RandomAccess
list of the k
least
elements in ascending orderIllegalArgumentException
- if k
is negative@Beta public <E extends T> List<E> greatestOf(Iterable<E> iterable, int k)
k
greatest elements of the given iterable according to
this ordering, in order from greatest to least. If there are fewer than
k
elements present, all will be included.
The implementation does not necessarily use a stable sorting algorithm; when multiple elements are equivalent, it is undefined which will come first.
RandomAccess
list of the k
greatest
elements in descending orderIllegalArgumentException
- if k
is negativepublic int binarySearch(List<? extends T> sortedList, @Nullable T key)
Searches
sortedList
for key
using the binary search algorithm. The
list must be sorted using this ordering.sortedList
- the list to be searchedkey
- the key to be searched forpublic <E extends T> List<E> sortedCopy(Iterable<E> iterable)
Unlike Sets.newTreeSet(Iterable)
, this method does not discard
elements that are duplicates according to the comparator. The sort
performed is stable, meaning that such elements will appear in the
resulting list in the same order they appeared in the input.
iterable
- the elements to be copied and sortedpublic <E extends T> ImmutableList<E> immutableSortedCopy(Iterable<E> iterable)
Unlike Sets.newTreeSet(Iterable)
, this method does not discard
elements that are duplicates according to the comparator. The sort
performed is stable, meaning that such elements will appear in the
resulting list in the same order they appeared in the input.
iterable
- the elements to be copied and sortedNullPointerException
- if iterable
or any of its elements is
nullpublic boolean isOrdered(Iterable<? extends T> iterable)
true
if each element in iterable
after the first is
greater than or equal to the element that preceded it, according to this
ordering. Note that this is always true when the iterable has fewer than
two elements.public boolean isStrictlyOrdered(Iterable<? extends T> iterable)
true
if each element in iterable
after the first is
strictly greater than the element that preceded it, according to
this ordering. Note that this is always true when the iterable has fewer
than two elements.@Beta public <E extends T> E max(Iterator<E> iterator)
hasNext()
method will return
false
.iterator
- the iterator whose maximum element is to be determinedNoSuchElementException
- if iterator
is emptyClassCastException
- if the parameters are not mutually
comparable under this ordering.public <E extends T> E max(Iterable<E> iterable)
iterable
- the iterable whose maximum element is to be determinedNoSuchElementException
- if iterable
is emptyClassCastException
- if the parameters are not mutually
comparable under this ordering.public <E extends T> E max(@Nullable E a, @Nullable E b, @Nullable E c, E... rest)
a
- value to compare, returned if greater than or equal to the rest.b
- value to comparec
- value to comparerest
- values to compareClassCastException
- if the parameters are not mutually
comparable under this ordering.public <E extends T> E max(@Nullable E a, @Nullable E b)
Implementation note: this method is invoked by the default
implementations of the other max
overloads, so overriding it will
affect their behavior.
a
- value to compare, returned if greater than or equal to b.b
- value to compare.ClassCastException
- if the parameters are not mutually
comparable under this ordering.@Beta public <E extends T> E min(Iterator<E> iterator)
hasNext()
method will return
false
.iterator
- the iterator whose minimum element is to be determinedNoSuchElementException
- if iterator
is emptyClassCastException
- if the parameters are not mutually
comparable under this ordering.public <E extends T> E min(Iterable<E> iterable)
iterable
- the iterable whose minimum element is to be determinedNoSuchElementException
- if iterable
is emptyClassCastException
- if the parameters are not mutually
comparable under this ordering.public <E extends T> E min(@Nullable E a, @Nullable E b, @Nullable E c, E... rest)
a
- value to compare, returned if less than or equal to the rest.b
- value to comparec
- value to comparerest
- values to compareClassCastException
- if the parameters are not mutually
comparable under this ordering.public <E extends T> E min(@Nullable E a, @Nullable E b)
Implementation note: this method is invoked by the default
implementations of the other min
overloads, so overriding it will
affect their behavior.
a
- value to compare, returned if less than or equal to b.b
- value to compare.ClassCastException
- if the parameters are not mutually
comparable under this ordering.Copyright © 2010-2012. All Rights Reserved.