java.lang.Comparable接口翻译及详解

import java.util.*;

/**
 * This interface imposes a total ordering on the objects of each class that
 * implements it.  This ordering is referred to as the class's natural
 * ordering, and the class's compareTo method is referred to as
 * its natural comparison method.

 * 
 * 此接口对实现它的每一个类的对象施加一个总排序。
 * 这个排序被称作类的自然排序，而类的compareTo方法被称为它的自然比较方法。

 *
 * Lists (and arrays) of objects that implement this interface can be sorted
 * automatically by {@link Collections#sort(List) Collections.sort} (and
 * {@link Arrays#sort(Object[]) Arrays.sort}).  Objects that implement this
 * interface can be used as keys in a {@linkplain SortedMap sorted map} or as
 * elements in a {@linkplain SortedSet sorted set}, without the need to
 * specify a {@linkplain Comparator comparator}.

 * 
 * 实现此接口的对象的List(和数组)可以通过Collections.sort(和Arrays.sort)自动排序。
 * 实现该接口的对象可以作为SortedMap中的键，或者作为SortedSet集合中的元素，并且不需要指定Comparator比较器。

 *
 * The natural ordering for a class C is said to be consistent
 * with equals if and only if e1.compareTo(e2) == 0 has
 * the same boolean value as e1.equals(e2) for every
 * e1 and e2 of class C.  Note that null
 * is not an instance of any class, and e.compareTo(null) should
 * throw a NullPointerException even though e.equals(null)
 * returns false.

 * 
 * 当且仅当对于任意一个C类的对象e1和e2，e1.compareTo(e2) == 0的返回和e1.equals(e2)的返回具有相同的boolean值，那么这个C类的自然排序和equals方法被称作是一致的。
 * 需要注意的是null不是任何一个类的实例，即使e.equals(null)返回false，e.compareTo(null)也应该抛出NullPointerException。

 *
 * It is strongly recommended (though not required) that natural orderings be
 * consistent with equals.  This is so because sorted sets (and sorted maps)
 * without explicit comparators behave "strangely" when they are used with
 * elements (or keys) whose natural ordering is inconsistent with equals.  In
 * particular, such a sorted set (or sorted map) violates the general contract
 * for set (or map), which is defined in terms of the equals
 * method.

 * 
 * 强烈建议自然排序与equals方法保持一致(虽然不是必须的)。
 * 这是因为没有显式比较器的有序set(和有序map)，当他们的自然排序与equals方法表现的不一致时，他们在使用元素(或键)时会表现的很奇怪。
 * 特别是，这样的有序set(或者有序map)违反了使用equals方法定义的set(或者map)的一般约定。

 *
 * For example, if one adds two keys a and b such that
 * {@code (!a.equals(b) && a.compareTo(b) == 0)} to a sorted
 * set that does not use an explicit comparator, the second add
 * operation returns false (and the size of the sorted set does not increase)
 * because a and b are equivalent from the sorted set's
 * perspective.

 * 
 * 例如，如果将两个键a和b添加到一个没有使用显式比较器的有序set中，
 * (!a.equals(b)返回true) && (a.compareTo(b) == 0返回false)，整体返回false，
 * 那么第二个add操作返回false(有序set的大小也不会增加)，因为在有序set的角度来看a和b是相同的。

 *
 * Virtually all Java core classes that implement Comparable have natural
 * orderings that are consistent with equals.  One exception is
 * java.math.BigDecimal, whose natural ordering equates
 * BigDecimal objects with equal values and different precisions
 * (such as 4.0 and 4.00).

 * 
 * 几乎所有实现了Comparable接口的Java核心类都具有与equals方法一致的自然排序。
 * 有一个特例是java.math.BigDecimal，其自然排序相当于具有相同值和不同精度的BigDecimal对象(例如4.0和4.00)。
 * 当值相同，但是精度不同时compareTo方法返回0，而equals方法返回false，详见BigDecimal中的equals和compareTo方法的具体实现。

 *
 * For the mathematically inclined, the relation that defines
 * the natural ordering on a given class C is:
 *       {(x, y) such that x.compareTo(y) <= 0}.
 * 
 The quotient for this total order is: 
 *       {(x, y) such that x.compareTo(y) == 0}.
 * 
 *
 * It follows immediately from the contract for compareTo that the
 * quotient is an equivalence relation on C, and that the
 * natural ordering is a total order on C.  When we say that a
 * class's natural ordering is consistent with equals, we mean that the
 * quotient for the natural ordering is the equivalence relation defined by
 * the class's {@link Object#equals(Object) equals(Object)} method:
 *     {(x, y) such that x.equals(y)}. 

 *     
 * This interface is a member of the
 * 
 * Java Collections Framework.
 *
 * @param  the type of objects that this object may be compared to
 *
 * @author  Josh Bloch
 * @see java.util.Comparator
 * @since 1.2
 */
public interface Comparable {
	/**
	 * Compares this object with the specified object for order.  Returns a
	 * negative integer, zero, or a positive integer as this object is less
	 * than, equal to, or greater than the specified object.

	 * 
	 * 将本对象与指定对象进行比较。当本对象小于指定对象时返回一个负数，等于指定对象时返回0，当大于指定对象时返回一个正数。

	 *
	 * 
The implementor must ensure sgn(x.compareTo(y)) ==
	 * -sgn(y.compareTo(x)) for all x and y.  (This
	 * implies that x.compareTo(y) must throw an exception iff
	 * y.compareTo(x) throws an exception.)

	 * 
	 * 实现者必须确保对于所有x和y，sgn(x.compareTo(y)) == -sgn(y.compareTo(x))，二者相等。
	 * sgn函数用于返回参数的符号，详见138行。意思是x.compareTo(y)和(y.compareTo(x))二者的返回值的符号应该是相反的。
	 * 这意味着当且仅当y.compareTo(x)抛出一个异常时，x.compareTo(y)也必须抛出一个异常。

	 *
	 * 
The implementor must also ensure that the relation is transitive:
	 * (x.compareTo(y)>0 && y.compareTo(z)>0) implies
	 * x.compareTo(z)>0.

	 * 
	 * 实现者还必须确保关系是可传递的：
	 * 如果(x.compareTo(y)>0 并且 y.compareTo(z)>0)，那么意味着x.compareTo(z)>0。

	 *
	 * 
Finally, the implementor must ensure that x.compareTo(y)==0
	 * implies that sgn(x.compareTo(z)) == sgn(y.compareTo(z)), for
	 * all z.

	 * 
	 * 最后，实现者还必须确保如果x.compareTo(y)==0，那么意味着sgn(x.compareTo(z)) == sgn(y.compareTo(z))。

	 *
	 * 
It is strongly recommended, but not strictly required that
	 * (x.compareTo(y)==0) == (x.equals(y)).  Generally speaking, any
	 * class that implements the Comparable interface and violates
	 * this condition should clearly indicate this fact.  The recommended
	 * language is "Note: this class has a natural ordering that is
	 * inconsistent with equals."

	 * 
	 * 强烈建议，但是不严格要求(x.compareTo(y)==0) == (x.equals(y))。一般来说，
	 * 任何一个实现了Comparable接口的类，如果违反了这个条件应该清楚地说明这一事实。
	 * 推荐的描述是：注意，这个类的自然排序和equals不一致。

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

	 * 
	 * 在前面的描述中，sgn(表达式)的符号表示数学符号函数，定义为返回-1、0或1，根据表达式的值为负、零或正。

	 *
	 * @param   o the object to be compared.
	 * @return  a negative integer, zero, or a positive integer as this object
	 *          is less than, equal to, or greater than the specified object.
	 *
	 * @throws NullPointerException if the specified object is null

	 * 如果指定的对象是null，那么抛出NullPointerException

	 * 
	 * @throws ClassCastException if the specified object's type prevents it
	 *         from being compared to this object.

	 * 如果指定对象的类型阻止它与本对象进行比较，那么抛出ClassCastException

	 */
	public int compareTo(T o);
}