Official Definition
From the reference docs of Comparable.compareTo(T):
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.
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.)
The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies 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.
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."
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.
My Version
In short:
this.compareTo(that)
returns
- a negative int if this < that
- 0 if this == that
- a positive int if this > that
where the implementation of this method determines the actual semantics of < > and == (I don't mean == in the sense of java's object identity operator)
Examples
"abc".compareTo("def")
will yield something smaller than 0 as abc is alphabetically before def.
Integer.valueOf(2).compareTo(Integer.valueOf(1))
will yield something larger than 0 because 2 is larger than 1.
Some additional points
Note: It is good practice for a class that implements Comparable to declare the semantics of it's compareTo() method in the javadocs.
Note: you should read at least one of the following:
- the Object Ordering section of the Collection Trail in the Sun Java Tutorial
- Effective Java by Joshua Bloch, especially item 12: Consider implementing Comparable
- Java Generics and Collections by Maurice Naftalin, Philip Wadler, chapter 3.1: Comparable
Warning: you should never rely on the return values of compareTo being -1, 0 and 1. You should always test for x < 0, x == 0, x > 0, respectively.
Official Definition
From the reference docs of Comparable.compareTo(T):
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.
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.)
The implementor must also ensure that the relation is transitive: (x.compareTo(y)>0 && y.compareTo(z)>0) implies 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.
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."
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.
My Version
In short:
this.compareTo(that)
returns
- a negative int if this < that
- 0 if this == that
- a positive int if this > that
where the implementation of this method determines the actual semantics of < > and == (I don't mean == in the sense of java's object identity operator)
Examples
"abc".compareTo("def")
will yield something smaller than 0 as abc is alphabetically before def.
Integer.valueOf(2).compareTo(Integer.valueOf(1))
will yield something larger than 0 because 2 is larger than 1.
Some additional points
Note: It is good practice for a class that implements Comparable to declare the semantics of it's compareTo() method in the javadocs.
Note: you should read at least one of the following:
- the Object Ordering section of the Collection Trail in the Sun Java Tutorial
- Effective Java by Joshua Bloch, especially item 12: Consider implementing Comparable
- Java Generics and Collections by Maurice Naftalin, Philip Wadler, chapter 3.1: Comparable
Warning: you should never rely on the return values of compareTo being -1, 0 and 1. You should always test for x < 0, x == 0, x > 0, respectively.
I use this mnemonic :
a.compareTo(b) < 0 // a < b
a.compareTo(b) > 0 // a > b
a.compareTo(b) == 0 // a == b
You keep the signs and always compare the result of compareTo() to 0
Videos
What is the purpose of the compareTo method in Java?
Which classes in Java implement the compareTo method?
How does the compareTo method differ from the equals method in Java?
From what I have been reading, the compareTo() method returns the difference of the Unicode numerical values of two Strings when they are compared with each other. For instance, the String "hello" when compared with the String "hello" returns an integer value of zero, since they both have exactly the same Unicode characters in them. Based on my understanding of this method, "hello" should return zero when compared to "olleh", because the two Strings have the exact same Unicode characters in them. Instead, though, I am getting integer value of 7 returned to the console. Can someone break this down a bit for me to help me understand it better? Thanks in advance. Here is my code:
String str1 = "hello";String str2 = "olleh";System.out.println(str1.compareTo(str2)); // 7
The general contract of Comparable.compareTo(o) is to return
- a positive integer if this is greater than the other object.
- a negative integer if this is lower than the other object.
- 0 if this is equals to the other object.
In your example "ab2".compareTo("ac3") == -1 and "ab2".compareTo("ab3") == -1 only means that "ab2" is lower than both "ac3" and "ab3". You cannot conclude anything regarding "ac3" and "ab3" with only these examples.
This result is expected since b comes before c in the alphabet (so "ab2" < "ac3") and 2 comes before 3 (so "ab2" < "ab3"): Java sorts Strings lexicographically.
compareTo for Strings returns -1 if the first String (the one for which the method is called) comes before the second String (the method's argument) in lexicographical order. "ab2" comes before "ab3" (since the first two characters are equal and 2 comes before 3) and also before "ac3" (since the first character is equal and b comes before c), so both comparisons return -1.