javadoc.com.google.common.collect.Ordering.html Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of guava-osgi

Repackaging of Google Guava libraries as OSGi bundle

The newest version!








Ordering (Guava: Google Core Libraries for Java 11.0.1 API)























  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD









com.google.common.collect


Class Ordering<T>
java.lang.Object
  com.google.common.collect.Ordering<T>


All Implemented Interfaces: 
Comparator<T>



@GwtCompatible
public abstract class Ordering<T>extends Object
implements Comparator<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 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.




Since:
  2.0 (imported from Google Collections Library)
Author:
  Jesse Wilson, Kevin Bourrillion











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)



           







<U extends T> 


Ordering<U>



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> 


List<E>



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> 


ImmutableList<E>



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> 


List<E>



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> 


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> 


E



max(E a,
       E b)



          Returns the greater of the two values according to this ordering.







<E extends T> 


E



max(E a,
       E b,
       E c,
       E... rest)



          Returns the greatest of the specified values according to this ordering.







<E extends T> 


E



max(Iterable<E> iterable)



          Returns the greatest of the specified values according to this ordering.







<E extends T> 


E



max(Iterator<E> iterator)



          Returns the greatest of the specified values according to this ordering.







<E extends T> 


E



min(E a,
       E b)



          Returns the lesser of the two values according to this ordering.







<E extends T> 


E



min(E a,
       E b,
       E c,
       E... rest)



          Returns the least of the specified values according to this ordering.







<E extends T> 


E



min(Iterable<E> iterable)



          Returns the least of the specified values according to this ordering.







<E extends T> 


E



min(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<S>



nullsFirst()



          Returns an ordering that treats null as less than all other values
 and uses this to compare non-null values.







<S extends T> 


Ordering<S>



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> 


Ordering<S>



reverse()



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







<E extends T> 


List<E>



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




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 a 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.











from
@GwtCompatible(serializable=true)
public static <T> Ordering<T> from(Comparator<T> comparator)

Returns an ordering for a pre-existing 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.





Parameters:
comparator - the comparator that defines the order





from
@GwtCompatible(serializable=true)
@Deprecated
public static <T> Ordering<T> from(Ordering<T> ordering)

Deprecated. no need to use this

Simply 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 to 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.





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 null
IllegalArgumentException - if valuesInOrder contains any
     duplicate values (according to Object.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 to 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.





Parameters:
leastValue - the value which the returned comparator should consider
     the "least" of all values
remainingValuesInOrder - 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 null
IllegalArgumentException - if any duplicate values (according to
     Object.equals(Object)) are present among the method arguments





arbitrary
public static Ordering<Object> arbitrary()

Returns an arbitrary ordering over all objects, for which 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.





Since:
  2.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 by toString(). It does not
 support null values.

 The comparator is serializable.











compound
@GwtCompatible(serializable=true)
public 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. The returned ordering is based on the state of
 the 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.





Parameters:
comparators - the comparators to try in order





compound
@GwtCompatible(serializable=true)
public <U extends T> Ordering<U> 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.
 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.











reverse
@GwtCompatible(serializable=true)
public <S extends T> Ordering<S> reverse()

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











onResultOf
@GwtCompatible(serializable=true)
public <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. For
 example, to compare objects by their string forms, in a case-insensitive
 manner, use:    Ordering.from(String.CASE_INSENSITIVE_ORDER)
       .onResultOf(Functions.toStringFunction())











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 to ordering.reverse().lexicographical() (consider how
 each would order [1] and [1, 1]).





Since:
  2.0






nullsFirst
@GwtCompatible(serializable=true)
public <S extends T> Ordering<S> nullsFirst()

Returns an ordering that treats null as less than all other values
 and uses this to compare non-null values.











nullsLast
@GwtCompatible(serializable=true)
public <S extends T> Ordering<S> nullsLast()

Returns an ordering that treats null as greater than all other
 values and uses this ordering to compare non-null values.











compare
public abstract int compare(@Nullable
                            T left,
                            @Nullable
                            T right)


Specified by:
compare in interface Comparator<T>








leastOf
@Beta
public <E extends T> List<E> 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.  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.






Returns:
an immutable RandomAccess list of the k least
     elements in ascending order
Throws:
IllegalArgumentException - if k is negative
Since:
  8.0






greatestOf
@Beta
public <E extends T> List<E> 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. 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.






Returns:
an immutable RandomAccess list of the k greatest
     elements in descending order
Throws:
IllegalArgumentException - if k is negative
Since:
  8.0






binarySearch
public 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.





Parameters:
sortedList - the list to be searched
key - the key to be searched for





sortedCopy
public <E extends T> List<E> sortedCopy(Iterable<E> iterable)

Returns a copy of the given iterable sorted by this ordering. The input is
 not modified. The returned list is modifiable, 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
 resulting list in the same order they appeared in the input.





Parameters:
iterable - the elements to be copied and sorted
Returns:
a new list containing the given elements in sorted order





immutableSortedCopy
public <E extends T> ImmutableList<E> immutableSortedCopy(Iterable<E> iterable)

Returns an immutable copy of the given iterable 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
 resulting list in the same order they appeared in the input.





Parameters:
iterable - the elements to be copied and sorted
Returns:
a new immutable list containing the given elements in sorted order
Throws:
NullPointerException - if iterable or any of its elements is
     null
Since:
  3.0






isOrdered
public 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. Note that this is always true when the iterable has fewer than
 two elements.











isStrictlyOrdered
public 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. Note that this is always true when the iterable has fewer
 than two elements.











max
@Beta
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: its hasNext() method will return
 false.





Parameters:
iterator - the iterator whose maximum element is to be determined
Throws:
NoSuchElementException - if iterator is empty
ClassCastException - 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.





Parameters:
iterable - the iterable whose maximum element is to be determined
Throws:
NoSuchElementException - if iterable is empty
ClassCastException - if the parameters are not mutually
     comparable under this ordering.





max
public <E extends T> E max(@Nullable
                           E a,
                           @Nullable
                           E b,
                           @Nullable
                           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.





Parameters:
a - value to compare, returned if greater than or equal to the rest.
b - value to compare
c - value to compare
rest - values to compare
Throws:
ClassCastException - if the parameters are not mutually
     comparable under this ordering.





max
public <E extends T> E max(@Nullable
                           E a,
                           @Nullable
                           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.





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.





min
@Beta
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: its hasNext() method will return
 false.





Parameters:
iterator - the iterator whose minimum element is to be determined
Throws:
NoSuchElementException - if iterator is empty
ClassCastException - 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.





Parameters:
iterable - the iterable whose minimum element is to be determined
Throws:
NoSuchElementException - if iterable is empty
ClassCastException - if the parameters are not mutually
     comparable under this ordering.





min
public <E extends T> E min(@Nullable
                           E a,
                           @Nullable
                           E b,
                           @Nullable
                           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.





Parameters:
a - value to compare, returned if less than or equal to the rest.
b - value to compare
c - value to compare
rest - values to compare
Throws:
ClassCastException - if the parameters are not mutually
     comparable under this ordering.





min
public <E extends T> E min(@Nullable
                           E a,
                           @Nullable
                           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.





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.














  
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 







  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD






Copyright © 2010-2012. All Rights Reserved.

javadoc.com.google.common.collect.Ordering.html Maven / Gradle / Ivy

com.google.common.collect Class Ordering<T>

Ordering

natural

from

from

explicit

explicit

arbitrary

usingToString

compound

compound

reverse

onResultOf

lexicographical

nullsFirst

nullsLast

compare

leastOf

greatestOf

binarySearch

sortedCopy

immutableSortedCopy

isOrdered

isStrictlyOrdered

max

max

max

max

min

min

min

min

com.google.common.collect
Class Ordering<T>