

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object com.google.common.collect.Ordering<T>
@GwtCompatible public abstract class Ordering<T>
A comparator with added methods to support common functions. For example:
if (Ordering.from(comparator).reverse().isOrdered(list)) { ... }
The from(Comparator)
method returns the equivalent Ordering
instance for a preexisting 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.
Constructor Summary  

protected 
Ordering()
Constructs a new instance of this class (only invokable by the subclass constructor, typically implicit). 
Method Summary  

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)
Searches
sortedList for key using the binary search algorithm. 

abstract int 
compare(T left,
T right)
Compares its two arguments for order. 


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

compound(Iterable<? extends Comparator<? super T>> comparators)
Returns an ordering which tries each given comparator in order until a nonzero result is found, returning that result, and returning zero only if all comparators return zero. 

static

explicit(List<T> valuesInOrder)
Returns an ordering that compares objects according to the order in which they appear in the given list. 

static

explicit(T leastValue,
T... remainingValuesInOrder)
Returns an ordering that compares objects according to the order in which they are given to this method. 

static

from(Comparator<T> comparator)
Returns an ordering for a preexisting comparator . 

static

from(Ordering<T> ordering)
Deprecated. no need to use this 


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. 


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. 


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. 


lexicographical()
Returns a new ordering which sorts iterables by comparing corresponding elements pairwise until a nonzero result is found; imposes "dictionary order". 


max(E a,
E b)
Returns the greater of the two values according to this ordering. 


max(E a,
E b,
E c,
E... rest)
Returns the greatest of the specified values according to this ordering. 


max(Iterable<E> iterable)
Returns the greatest of the specified values according to this ordering. 


min(E a,
E b)
Returns the lesser of the two values according to this ordering. 


min(E a,
E b,
E c,
E... rest)
Returns the least of the specified values according to this ordering. 


min(Iterable<E> iterable)
Returns the least of the specified values according to this ordering. 

static

natural()
Returns a serializable ordering that uses the natural order of the values. 


nullsFirst()
Returns an ordering that treats null as less than all other values
and uses this to compare nonnull values. 


nullsLast()
Returns an ordering that treats null as greater than all other
values and uses this ordering to compare nonnull values. 


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 . 


reverse()
Returns the reverse of this ordering; the Ordering equivalent to
Collections.reverseOrder(Comparator) . 


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() . 
Methods inherited from class java.lang.Object 

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait 
Methods inherited from interface java.util.Comparator 

equals 
Constructor Detail 

protected Ordering()
Method Detail 

@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 preexisting, 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 induce
NullPointerException
 if any of the provided values is null
IllegalArgumentException
 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
follow
NullPointerException
 if any of the provided values is null
IllegalArgumentException
 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 identitybased, 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 nondeterministic 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 caseinsensitive
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 nonnull values.
@GwtCompatible(serializable=true) public <S extends T> Ordering<S> nullsLast()
null
as greater than all other
values and uses this ordering to compare nonnull values.
public abstract int compare(@Nullable T left, @Nullable T right)
java.util.Comparator
In the foregoing description, the notation sgn(expression) designates the mathematical signum function, which is defined to return one of 1, 0, or 1 according to whether the value of expression is negative, zero or positive.
The implementor must ensure that sgn(compare(x, y)) == sgn(compare(y, x)) for all x and y. (This implies that compare(x, y) must throw an exception if and only if compare(y, x) throws an exception.)
The implementor must also ensure that the relation is transitive: ((compare(x, y)>0) && (compare(y, z)>0)) implies compare(x, z)>0.
Finally, the implementor must ensure that compare(x, y)==0 implies that sgn(compare(x, z))==sgn(compare(y, z)) for all z.
It is generally the case, but not strictly required that (compare(x, y)==0) == (x.equals(y)). Generally speaking, any comparator that violates this condition should clearly indicate this fact. The recommended language is "Note: this comparator imposes orderings that are inconsistent with equals."
compare
in interface Comparator<T>
left
 the first object to be compared.right
 the second object to be compared.
@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 order
IllegalArgumentException
 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 order
IllegalArgumentException
 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 sorted
public <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 sorted
NullPointerException
 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.
public <E extends T> E max(Iterable<E> iterable)
iterable
 the iterable whose maximum element is to be determined
NoSuchElementException
 if iterable
is empty
ClassCastException
 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 compare
ClassCastException
 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.public <E extends T> E min(Iterable<E> iterable)
iterable
 the iterable whose minimum element is to be determined
NoSuchElementException
 if iterable
is empty
ClassCastException
 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 compare
ClassCastException
 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.


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 