Chapter 3 -- Ordering

Guava's fluent comparator class, Ordering, explained. 
explained

Updated Jun 27, 2013 by cpov...@google.com

Example 例子

assertTrue(byLengthOrdering.reverse().isOrdered(list));

Overview 总览

Ordering is Guava's "fluent" Comparator class, which can be used to build complex comparators and apply them to collections of objects.

Ordering是Guava的"fluent"比较器类, 他可以用来组件复杂的比较器并应用到集合中

At its core, an Ordering instance is nothing more than a special Comparator instance. Ordering simply takes the methods that rely on aComparator (for example, Collections.max) and makes them available as instance methods. For additional power, Ordering class provides chaining methods to tweak and enhance existing comparators.

它的核心内, 一个 Ordering 实例只不过是一个特殊的比较器实例, Ordering简单地让这些方法依赖一个comparator(例如 Collections.max) 并使它们作为实例方法成为可能. 另外,Ordering提供了链式方法调用来调整和提高现有的comparator的能力

Creation 创建

Common orderings are provided by static methods:

通常ordering由以下静态方法提供:

Method	Description
natural()	Uses the natural ordering on Comparable types. 在可比较的类型上使用natural ordering, 这个方法返回一个NaturalOrdering, 它的比较方法使用了对象默认的compareTo实现
usingToString()	Compares objects by the lexicographical ordering of their string representations, as returned by toString(). 通过词典编撰的字符串顺序来比较两个object, 使用的是对象的Object.toString().CompareTo()方法来比较

Making a preexisting Comparator into an Ordering is as simple as using Ordering.from(Comparator).

使用一个已经存储在的comparator来生成Ordering很简单: Ordering.from(Comparator)

But the more common way to create a custom Ordering is to skip the Comparator entirely in favor of extending the Ordering abstract class directly:

更常用的创建自定义Ordering的方法是为了直接支持继承Ordering完全跳过Comparator:

Ordering<String> byLengthOrdering =new Ordering<String>(){
  publicint compare(String left,String right){
    returnInts.compare(left.length(), right.length());
  }
};

Chaining 链式调用

A given Ordering can be wrapped to obtain derived orderings. Some of the most commonly used variations include:

一个Ordering可以被包装成派生的ordering. 一些最常用的变体如下:

Method	Description
reverse()	Returns the reverse ordering. 返回逆向的ordering, 相当于本来是left.compareTo(right), 现在是 right.compareTo(left)
nullsFirst()	Returns an Ordering that orders nulls before non-null elements, and otherwise behaves the same as the original Ordering. See also nullsLast(). 返回一个先排序nulls在排序non-null元素的Ordering, 其他方面和原始的Ordering一样
compound(Comparator)	Returns an Ordering which uses the specified Comparator to "break ties." 返回一个使用指定comparator的Ordering, 这个指定的comparator会作为第二比较器来使用
lexicographical()	Returns an Ordering that orders iterables lexicographically by their elements. 返回一个根据元素的字典顺序来排序遍历器(iterables)的ordering. 例如, [] < [1] < [1, 1] < [1, 2] < [2]
onResultOf(Function)	Returns an Ordering which orders values by applying the function to them and then comparing the results using the original Ordering. 返回一个先用function的apply方法处理待排序的值然后再比较处理后的结果的Ordering

For example, let's say you want a comparator for the class...

举个例子, 比如你想要一个class的comparator

classFoo{
  @Nullable String sortedBy;
  int notSortedBy;
}

...that can deal with null values of sortedBy. Here is a solution built atop the chaining methods:

这可以处理sortedBy的null值.这里有一个使用链式调用的解决方案:

Ordering<Foo> ordering = Ordering.natural().nullsFirst().onResultOf(new Function<Foo,String>(){
  publicString apply(Foo foo){
    return foo.sortedBy;
  }
});

When reading a chain of Ordering calls, work "backward" from right to left. The example above orders Foo instances by looking up theirsortedBy field values, first moving any null sortedBy values to the top and then sorting the remaining values by natural string ordering. This backward order arises because each chaining call is "wrapping" the previous Ordering into a new one.

当读取一个链式的ordering调用, 工作顺序是用右向左"反向"的. 上面的例子的顺序是先查找sortedBy的值, 然后将null的sortedBy的值移到最前面,然后将剩下的值按照自然字符串顺序进行排序.这种反向顺序出现是因为每个链的调用都被将一个Ordering包装成一个新的Ordering.

(Exception to the "backwards" rule: For chains of calls to compound, read from left to right. To avoid confusion, avoid intermixing compound calls with other chained calls.)

("反向"规则的例外: 对compound的连时调用, 是从左到右的.为了避免困惑, 避免将compound和其他链式方法混在一起调用)

Chains longer than a few calls can be difficult to understand. We recommend limiting chaining to about three calls as in the example above. Even then, you may wish to simplify the code by separating out intermediate objects such as Function instances:

太长的链式调用会让人难以理解.我们建议将链式调用限制在三个方法内.即使那样,你也可能希望通过分离中间对象(例如Function匿名类)来简化代码:

Ordering<Foo> ordering =Ordering.natural().nullsFirst().onResultOf(sortKeyFunction);

Application 应用

Guava provides a number of methods to manipulate or examine values or collections using the ordering. We list some of the most popular here.

Guava提供了一系列的方法来使用Ordering操作和检查值和集合.下面列举一些最常用的一些方法:

Method	Description	See also
greatestOf(Iterable iterable, int k)	Returns the k greatest elements of the specified iterable, according to this ordering, in order from greatest to least. Not necessarily stable. 返回指定的iterable最大的k个元素, 根据当前ordering的规则, 顺序是从最大到最小的.	leastOf
isOrdered(Iterable)	Tests if the specified Iterable is in nondecreasing order according to this ordering. 测试指定的Iterable是否按照ordering的非降序顺序排列	isStrictlyOrdered
sortedCopy(Iterable)	Returns a sorted copy of the specified elements as a List. 返回一个Iterable的排序副本	immutableSortedCopy
min(E, E)	Returns the minimum of its two arguments according to this ordering. If the values compare as equal, the first argument is returned. 返回根据ordering判断的两个参数中的最小值.假如两个参数一样大,则返回第一个参数	max(E, E)
min(E, E, E, E...)	Returns the minimum of its arguments according to this ordering. If there are multiple least values, the first is returned. 返回根据ordering判断的多个参数中的最小值.如果有多个最小值,则返回第一个参数	max(E, E, E, E...)
min(Iterable)	Returns the minimum element of the specified Iterable. Throws a NoSuchElementException if the Iterable is empty. 返回Iterable中的最小值.如果Iterable是空的则抛出NoSuchElementException异常	max(Iterable), min(Iterator),max(Iterator)