Class Ordering<T extends @Nullable Object>
- java.lang.Object
-
- com.google.common.collect.Ordering<T>
-
- All Implemented Interfaces:
Comparator<T>
@GwtCompatible public abstract class Ordering<T extends @Nullable Object> extends Object implements Comparator<T>
A comparator, with additional methods to support common operations. This is an "enriched" version ofComparator
for pre-Java-8 users, in the same sense thatFluentIterable
is an enrichedIterable
for pre-Java-8 users.Three types of methods
Like other fluent types, there are three types of methods present: methods for acquiring, chaining, and using.Acquiring
The common ways to get an instance of
Ordering
are:- Subclass it and implement
compare(T, T)
instead of implementingComparator
directly - Pass a pre-existing
Comparator
instance tofrom(Comparator)
- Use the natural ordering,
natural()
Chaining
Then you can use the chaining methods to get an altered version of that
Ordering
, including:Using
Finally, use the resulting
Ordering
anywhere aComparator
is required, or use any of its special operations, such as:immutableSortedCopy(java.lang.Iterable<E>)
isOrdered(java.lang.Iterable<? extends T>)
/isStrictlyOrdered(java.lang.Iterable<? extends T>)
min(java.util.Iterator<E>)
/max(java.util.Iterator<E>)
Understanding complex orderings
Complex chained orderings like the following example can be challenging to understand.
Note that each chaining method returns a new ordering instance which is backed by the previous instance, but has the chance to act on values before handing off to that backing instance. As a result, it usually helps to read chained ordering expressions backwards. For example, whenOrdering<Foo> ordering = Ordering.natural() .nullsFirst() .onResultOf(getBarFunction) .nullsLast();
compare
is called on the above ordering:- First, if only one
Foo
is null, that null value is treated as greater - Next, non-null
Foo
values are passed togetBarFunction
(we will be comparingBar
values from now on) - Next, if only one
Bar
is null, that null value is treated as lesser - Finally, natural ordering is used (i.e. the result of
Bar.compareTo(Bar)
is returned)
Alas,
reverse()
is a little different. As you read backwards through a chain and encounter a call toreverse
, continue working backwards until a result is determined, and then reverse that result.Additional notes
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
andfunction
can themselves be serialized, thenordering.onResultOf(function)
can as well.For Java 8 users
If you are using Java 8, this class is now obsolete. Most of its functionality is now provided by
Stream
and byComparator
itself, and the rest can now be found as static methods in our newComparators
class. See each method below for further instructions. Whenever possible, you should change any references of typeOrdering
to be of typeComparator
instead. However, at this time we have no plan to deprecate this class.Many replacements involve adopting
Stream
, and these changes can sometimes make your code verbose. Whenever following this advice, you should check whetherStream
could be adopted more comprehensively in your code; the end result may be quite a bit simpler.See also
See the Guava User Guide article on
Ordering
.- Since:
- 2.0
- Author:
- Jesse Wilson, Kevin Bourrillion
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
Ordering()
Constructs a new instance of this class (only invokable by the subclass constructor, typically implicit).
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static Ordering<@Nullable Object>
allEqual()
Returns an ordering which treats all values as equal, indicating "no ordering." Passing this ordering to any stable sort algorithm results in no change to the order of elements.static Ordering<@Nullable Object>
arbitrary()
Returns an arbitrary ordering over all objects, for whichcompare(a, b) == 0
impliesa == b
(identity equality).int
binarySearch(List<? extends T> sortedList, T key)
Deprecated.UseCollections.binarySearch(List, Object, Comparator)
directly.abstract int
compare(T left, T right)
Compares its two arguments for order.static <T extends @Nullable Object>
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.<U extends T>
Ordering<U>compound(Comparator<? super U> secondaryComparator)
Returns an ordering which first uses the orderingthis
, but which in the event of a "tie", then delegates tosecondaryComparator
.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 extends @Nullable Object>
Ordering<T>from(Ordering<T> ordering)
Deprecated.no need to use thisstatic <T extends @Nullable Object>
Ordering<T>from(Comparator<T> comparator)
Returns an ordering based on an existing comparator instance.<E extends T>
List<E>greatestOf(Iterable<E> iterable, int k)
Returns thek
greatest elements of the given iterable according to this ordering, in order from greatest to least.<E extends T>
List<E>greatestOf(Iterator<E> iterator, int k)
Returns thek
greatest elements from the given iterator according to this ordering, in order from greatest to least.<E extends T>
ImmutableList<E>immutableSortedCopy(Iterable<E> elements)
Returns an immutable list containingelements
sorted by this ordering.boolean
isOrdered(Iterable<? extends T> iterable)
Returnstrue
if each element initerable
after the first is greater than or equal to the element that preceded it, according to this ordering.boolean
isStrictlyOrdered(Iterable<? extends T> iterable)
Returnstrue
if each element initerable
after the first is strictly greater than the element that preceded it, according to this ordering.<E extends T>
List<E>leastOf(Iterable<E> iterable, int k)
Returns thek
least elements of the given iterable according to this ordering, in order from least to greatest.<E extends T>
List<E>leastOf(Iterator<E> iterator, int k)
Returns thek
least elements from the given iterator according to this ordering, in order from least to greatest.<S extends T>
Ordering<Iterable<S>>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>
Emax(E a, E b)
Returns the greater of the two values according to this ordering.<E extends T>
Emax(E a, E b, E c, E... rest)
Returns the greatest of the specified values according to this ordering.<E extends T>
Emax(Iterable<E> iterable)
Returns the greatest of the specified values according to this ordering.<E extends T>
Emax(Iterator<E> iterator)
Returns the greatest of the specified values according to this ordering.<E extends T>
Emin(E a, E b)
Returns the lesser of the two values according to this ordering.<E extends T>
Emin(E a, E b, E c, E... rest)
Returns the least of the specified values according to this ordering.<E extends T>
Emin(Iterable<E> iterable)
Returns the least of the specified values according to this ordering.<E extends T>
Emin(Iterator<E> iterator)
Returns the least of the specified values according to this ordering.static <C extends Comparable>
Ordering<C>natural()
Returns a serializable ordering that uses the natural order of the values.<S extends T>
Ordering<@Nullable S>nullsFirst()
Returns an ordering that treatsnull
as less than all other values and usesthis
to compare non-null values.<S extends T>
Ordering<@Nullable S>nullsLast()
Returns an ordering that treatsnull
as greater than all other values and uses this ordering to compare non-null values.<F extends @Nullable Object>
Ordering<F>onResultOf(Function<F,? extends T> function)
Returns a new ordering onF
which orders elements by first applying a function to them, then comparing those results usingthis
.<S extends T>
Ordering<S>reverse()
Returns the reverse of this ordering; theOrdering
equivalent toCollections.reverseOrder(Comparator)
.<E extends T>
List<E>sortedCopy(Iterable<E> elements)
Returns a mutable list containingelements
sorted by this ordering; use this only when the resulting list may need further modification, or may containnull
.static Ordering<Object>
usingToString()
Returns an ordering that compares objects by the natural ordering of their string representations as returned bytoString()
.-
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, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong
-
-
-
-
Constructor Detail
-
Ordering
protected Ordering()
Constructs a new instance of this class (only invokable by the subclass constructor, typically implicit).
-
-
Method Detail
-
natural
@GwtCompatible(serializable=true) public static <C extends Comparable> Ordering<C> natural()
Returns a serializable ordering that uses the natural order of the values. The ordering throws aNullPointerException
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.Java 8 users: use
Comparator.naturalOrder()
instead.
-
from
@GwtCompatible(serializable=true) public static <T extends @Nullable Object> Ordering<T> from(Comparator<T> comparator)
Returns an ordering based on an existing comparator instance. Note that it is unnecessary to create a new anonymous inner class implementingComparator
just to pass it in here. Instead, simply subclassOrdering
and implement itscompare
method directly.Java 8 users: this class is now obsolete as explained in the class documentation, so there is no need to use this method.
- Parameters:
comparator
- the comparator that defines the order- Returns:
- comparator itself if it is already an
Ordering
; otherwise an ordering that wraps that comparator
-
from
@GwtCompatible(serializable=true) @Deprecated public static <T extends @Nullable Object> Ordering<T> from(Ordering<T> ordering)
Deprecated.no need to use thisSimply returns its argument.
-
explicit
@GwtCompatible(serializable=true) public 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. Only objects present in the list (according toObject.equals(java.lang.Object)
) may be compared. This comparator imposes a "partial ordering" over the typeT
. Subsequent changes to thevaluesInOrder
list will have no effect on the returned comparator. Null values in the 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.
- Parameters:
valuesInOrder
- the values that the returned comparator will be able to compare, in the order the comparator should induce- Returns:
- the comparator described above
- Throws:
NullPointerException
- if any of the provided values is nullIllegalArgumentException
- ifvaluesInOrder
contains any duplicate values (according toObject.equals(java.lang.Object)
)
-
explicit
@GwtCompatible(serializable=true) public 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. Only objects present in the argument list (according toObject.equals(java.lang.Object)
) may be compared. This comparator imposes a "partial ordering" over the typeT
. 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.
- Parameters:
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- Returns:
- the comparator described above
- Throws:
NullPointerException
- if any of the provided values is nullIllegalArgumentException
- if any duplicate values (according toObject.equals(Object)
) are present among the method arguments
-
allEqual
@GwtCompatible(serializable=true) public static Ordering<@Nullable Object> allEqual()
Returns an ordering which treats all values as equal, indicating "no ordering." Passing this ordering to any stable sort algorithm results in no change to the order of elements. Note especially thatsortedCopy(java.lang.Iterable<E>)
andimmutableSortedCopy(java.lang.Iterable<E>)
are stable, and in the returned instance these are implemented by simply copying the source list.Example:
Ordering.allEqual().nullsLast().sortedCopy( asList(t, null, e, s, null, t, null))
Assuming
t
,e
ands
are non-null, this returns[t, e, s, t, null, null, null]
regardless of the true comparison order of those three values (which might not even implementComparable
at all).Warning: by definition, this comparator is not consistent with equals (as defined here). Avoid its use in APIs, such as
TreeSet(Comparator)
, where such consistency is expected.The returned comparator is serializable.
Java 8 users: Use the lambda expression
(a, b) -> 0
instead (in certain cases you may need to cast that toComparator<YourType>
).- Since:
- 13.0
-
usingToString
@GwtCompatible(serializable=true) public static Ordering<Object> usingToString()
Returns an ordering that compares objects by the natural ordering of their string representations as returned bytoString()
. It does not support null values.The comparator is serializable.
Java 8 users: Use
Comparator.comparing(Object::toString)
instead.
-
arbitrary
public static Ordering<@Nullable Object> arbitrary()
Returns an arbitrary ordering over all objects, for whichcompare(a, b) == 0
impliesa == 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 byComparator
. Use caution when building aSortedSet
orSortedMap
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.- Since:
- 2.0
-
reverse
@GwtCompatible(serializable=true) public <S extends T> Ordering<S> reverse()
Returns the reverse of this ordering; theOrdering
equivalent toCollections.reverseOrder(Comparator)
.Java 8 users: Use
thisComparator.reversed()
instead.
-
nullsFirst
@GwtCompatible(serializable=true) public <S extends T> Ordering<@Nullable S> nullsFirst()
Returns an ordering that treatsnull
as less than all other values and usesthis
to compare non-null values.Java 8 users: Use
Comparator.nullsFirst(thisComparator)
instead.
-
nullsLast
@GwtCompatible(serializable=true) public <S extends T> Ordering<@Nullable S> nullsLast()
Returns an ordering that treatsnull
as greater than all other values and uses this ordering to compare non-null values.Java 8 users: Use
Comparator.nullsLast(thisComparator)
instead.
-
onResultOf
@GwtCompatible(serializable=true) public <F extends @Nullable Object> Ordering<F> onResultOf(Function<F,? extends T> function)
Returns a new ordering onF
which orders elements by first applying a function to them, then comparing those results usingthis
. For example, to compare objects by their string forms, in a case-insensitive manner, use:Ordering.from(String.CASE_INSENSITIVE_ORDER) .onResultOf(Functions.toStringFunction())
Java 8 users: Use
Comparator.comparing(function, thisComparator)
instead (you can omit the comparator if it is the natural order).
-
compound
@GwtCompatible(serializable=true) public <U extends T> Ordering<U> compound(Comparator<? super U> secondaryComparator)
Returns an ordering which first uses the orderingthis
, but which in the event of a "tie", then delegates tosecondaryComparator
. For example, to sort a bug list first by status and second by priority, you might usebyStatus.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.Java 8 users: Use
thisComparator.thenComparing(secondaryComparator)
instead. Depending on whatsecondaryComparator
is, one of the other overloads ofthenComparing
may be even more useful.
-
compound
@GwtCompatible(serializable=true) public static <T extends @Nullable Object> 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. The returned ordering is based on the state of thecomparators
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.Java 8 users: Use a chain of calls to
Comparator.thenComparing(Comparator)
, orcomparatorCollection.stream().reduce(Comparator::thenComparing).get()
(if the collection might be empty, also provide a default comparator as theidentity
parameter toreduce
).- Parameters:
comparators
- the comparators to try in order
-
lexicographical
@GwtCompatible(serializable=true) public <S extends T> Ordering<Iterable<S>> lexicographical()
Returns a new ordering which sorts iterables by comparing corresponding elements pairwise until a nonzero result is found; imposes "dictionary order". If the end of one iterable is reached, but not the other, the shorter iterable is considered to be less than the longer one. For example, a lexicographical natural ordering over integers considers[] < [1] < [1, 1] < [1, 2] < [2]
.Note that
ordering.lexicographical().reverse()
is not equivalent toordering.reverse().lexicographical()
(consider how each would order[1]
and[1, 1]
).Java 8 users: Use
Comparators.lexicographical(Comparator)
instead.- Since:
- 2.0
-
compare
@CanIgnoreReturnValue public abstract int compare(T left, T right)
Description copied from interface:java.util.Comparator
Compares its two arguments for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.The implementor must ensure that
sgn(compare(x, y)) == -sgn(compare(y, x))
for allx
andy
. (This implies thatcompare(x, y)
must throw an exception if and only ifcompare(y, x)
throws an exception.)The implementor must also ensure that the relation is transitive:
((compare(x, y)>0) && (compare(y, z)>0))
impliescompare(x, z)>0
.Finally, the implementor must ensure that
compare(x, y)==0
implies thatsgn(compare(x, z))==sgn(compare(y, z))
for allz
.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."In the foregoing description, the notation
sgn(
expression)
designates the mathematical signum function, which is defined to return one of-1
,0
, or1
according to whether the value of expression is negative, zero, or positive, respectively.- Specified by:
compare
in interfaceComparator<T extends @Nullable Object>
- Parameters:
left
- the first object to be compared.right
- the second object to be compared.- Returns:
- a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.
-
min
public <E extends T> E min(Iterator<E> iterator)
Returns the least of the specified values according to this ordering. If there are multiple least values, the first of those is returned. The iterator will be left exhausted: itshasNext()
method will returnfalse
.Java 8 users: Use
Streams.stream(iterator).min(thisComparator).get()
instead (but note that it does not guarantee which tied minimum element is returned).- Parameters:
iterator
- the iterator whose minimum element is to be determined- Throws:
NoSuchElementException
- ifiterator
is emptyClassCastException
- if the parameters are not mutually comparable under this ordering.- Since:
- 11.0
-
min
public <E extends T> E min(Iterable<E> iterable)
Returns the least of the specified values according to this ordering. If there are multiple least values, the first of those is returned.Java 8 users: If
iterable
is aCollection
, useCollections.min(collection, thisComparator)
instead. Otherwise, useStreams.stream(iterable).min(thisComparator).get()
instead. Note that these alternatives do not guarantee which tied minimum element is returned)- Parameters:
iterable
- the iterable whose minimum element is to be determined- Throws:
NoSuchElementException
- ifiterable
is emptyClassCastException
- if the parameters are not mutually comparable under this ordering.
-
min
public <E extends T> E min(E a, E b)
Returns the lesser of the two values according to this ordering. If the values compare as 0, the first is returned.Implementation note: this method is invoked by the default implementations of the other
min
overloads, so overriding it will affect their behavior.Note: Consider using
Comparators.min(a, b, thisComparator)
instead. IfthisComparator
isnatural()
, then useComparators.min(a, b)
.- Parameters:
a
- value to compare, returned if less than or equal to b.b
- value to compare.- Throws:
ClassCastException
- if the parameters are not mutually comparable under this ordering.
-
min
public <E extends T> E min(E a, E b, E c, E... rest)
Returns the least of the specified values according to this ordering. If there are multiple least values, the first of those is returned.Java 8 users: Use
Collections.min(Arrays.asList(a, b, c...), thisComparator)
instead (but note that it does not guarantee which tied minimum element is returned).- Parameters:
a
- value to compare, returned if less than or equal to the rest.b
- value to comparec
- value to comparerest
- values to compare- Throws:
ClassCastException
- if the parameters are not mutually comparable under this ordering.
-
max
public <E extends T> E max(Iterator<E> iterator)
Returns the greatest of the specified values according to this ordering. If there are multiple greatest values, the first of those is returned. The iterator will be left exhausted: itshasNext()
method will returnfalse
.Java 8 users: Use
Streams.stream(iterator).max(thisComparator).get()
instead (but note that it does not guarantee which tied maximum element is returned).- Parameters:
iterator
- the iterator whose maximum element is to be determined- Throws:
NoSuchElementException
- ifiterator
is emptyClassCastException
- if the parameters are not mutually comparable under this ordering.- Since:
- 11.0
-
max
public <E extends T> E max(Iterable<E> iterable)
Returns the greatest of the specified values according to this ordering. If there are multiple greatest values, the first of those is returned.Java 8 users: If
iterable
is aCollection
, useCollections.max(collection, thisComparator)
instead. Otherwise, useStreams.stream(iterable).max(thisComparator).get()
instead. Note that these alternatives do not guarantee which tied maximum element is returned)- Parameters:
iterable
- the iterable whose maximum element is to be determined- Throws:
NoSuchElementException
- ifiterable
is emptyClassCastException
- if the parameters are not mutually comparable under this ordering.
-
max
public <E extends T> E max(E a, E b)
Returns the greater of the two values according to this ordering. If the values compare as 0, the first is returned.Implementation note: this method is invoked by the default implementations of the other
max
overloads, so overriding it will affect their behavior.Note: Consider using
Comparators.max(a, b, thisComparator)
instead. IfthisComparator
isnatural()
, then useComparators.max(a, b)
.- Parameters:
a
- value to compare, returned if greater than or equal to b.b
- value to compare.- Throws:
ClassCastException
- if the parameters are not mutually comparable under this ordering.
-
max
public <E extends T> E max(E a, E b, E c, E... rest)
Returns the greatest of the specified values according to this ordering. If there are multiple greatest values, the first of those is returned.Java 8 users: Use
Collections.max(Arrays.asList(a, b, c...), thisComparator)
instead (but note that it does not guarantee which tied maximum element is returned).- Parameters:
a
- value to compare, returned if greater than or equal to the rest.b
- value to comparec
- value to comparerest
- values to compare- Throws:
ClassCastException
- if the parameters are not mutually comparable under this ordering.
-
leastOf
public <E extends T> List<E> leastOf(Iterable<E> iterable, int k)
Returns thek
least elements of the given iterable according to this ordering, in order from least to greatest. If there are fewer thank
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.
Java 8 users: Use
Streams.stream(iterable).collect(Comparators.least(k, thisComparator))
instead.- Returns:
- an immutable
RandomAccess
list of thek
least elements in ascending order - Throws:
IllegalArgumentException
- ifk
is negative- Since:
- 8.0
-
leastOf
public <E extends T> List<E> leastOf(Iterator<E> iterator, int k)
Returns thek
least elements from the given iterator according to this ordering, in order from least to greatest. If there are fewer thank
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.
Java 8 users: Use
Streams.stream(iterator).collect(Comparators.least(k, thisComparator))
instead.- Returns:
- an immutable
RandomAccess
list of thek
least elements in ascending order - Throws:
IllegalArgumentException
- ifk
is negative- Since:
- 14.0
-
greatestOf
public <E extends T> List<E> greatestOf(Iterable<E> iterable, int k)
Returns thek
greatest elements of the given iterable according to this ordering, in order from greatest to least. If there are fewer thank
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.
Java 8 users: Use
Streams.stream(iterable).collect(Comparators.greatest(k, thisComparator))
instead.- Returns:
- an immutable
RandomAccess
list of thek
greatest elements in descending order - Throws:
IllegalArgumentException
- ifk
is negative- Since:
- 8.0
-
greatestOf
public <E extends T> List<E> greatestOf(Iterator<E> iterator, int k)
Returns thek
greatest elements from the given iterator according to this ordering, in order from greatest to least. If there are fewer thank
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.
Java 8 users: Use
Streams.stream(iterator).collect(Comparators.greatest(k, thisComparator))
instead.- Returns:
- an immutable
RandomAccess
list of thek
greatest elements in descending order - Throws:
IllegalArgumentException
- ifk
is negative- Since:
- 14.0
-
sortedCopy
public <E extends T> List<E> sortedCopy(Iterable<E> elements)
Returns a mutable list containingelements
sorted by this ordering; use this only when the resulting list may need further modification, or may containnull
. The input is not modified. The returned list is serializable and has random access.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 returned list in the same order they appeared inelements
.Performance note: According to our benchmarking on Open JDK 7,
immutableSortedCopy(java.lang.Iterable<E>)
generally performs better (in both time and space) than this method, and this method in turn generally performs better than copying the list and callingCollections.sort(List)
.
-
immutableSortedCopy
public <E extends T> ImmutableList<E> immutableSortedCopy(Iterable<E> elements)
Returns an immutable list containingelements
sorted by this ordering. The input is not modified.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 returned list in the same order they appeared inelements
.Performance note: According to our benchmarking on Open JDK 7, this method is the most efficient way to make a sorted copy of a collection.
- Throws:
NullPointerException
- if any element ofelements
isnull
- Since:
- 3.0
-
isOrdered
public boolean isOrdered(Iterable<? extends T> iterable)
Returnstrue
if each element initerable
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.Java 8 users: Use the equivalent
Comparators.isInOrder(Iterable, Comparator)
instead, since the rest ofOrdering
is mostly obsolete (as explained in the class documentation).
-
isStrictlyOrdered
public boolean isStrictlyOrdered(Iterable<? extends T> iterable)
Returnstrue
if each element initerable
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.Java 8 users: Use the equivalent
Comparators.isInStrictOrder(Iterable, Comparator)
instead, since the rest ofOrdering
is mostly obsolete (as explained in the class documentation).
-
binarySearch
@Deprecated public int binarySearch(List<? extends T> sortedList, T key)
Deprecated.UseCollections.binarySearch(List, Object, Comparator)
directly.Searches
sortedList
forkey
using the binary search algorithm. The list must be sorted using this ordering.- Parameters:
sortedList
- the list to be searchedkey
- the key to be searched for
-
-