What do the return values of Comparable.compareTo mean in Java?

Question

What is the difference between returning 0, returning 1 and returning -1 in compareTo() in Java?

if you have trouble remembering, (like i do), i simply imagine it as being a number subtraction operation `a-b` if `a` is bigger, the result is positive (+1) else, if `b` is bigger the result is negative...if they're equal its `0` — st0le, Sep 23 '10 at 10:27

Sean Patrick Floyd · Answer 1 · 2010-09-23T10:09:29.770

102

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.

edited Sep 23 '10 at 10:09

answered Sep 22 '10 at 07:22

Sean Patrick Floyd

292,901
67
465
588

Remember, in the documentation they talk about `sgn()`, not directly -1 and 1. You should add this to your short version. – Colin Hebert Sep 22 '10 at 15:03
I know. I prefer real language to mathematical mumbo-jumbo (boy am I glad that you can't downvote comments :-)), so I wrote *-1 (or smaller)* and *1 (or larger)*, respectively. – Sean Patrick Floyd Sep 22 '10 at 15:06
1

Interestingly, the official docs say **at no point** that a negative int actually means *this < that*. They just say that there are three distinct return values: a negative int, zero, and a positive int. One of them means *this < that*, one means *this > that* and one means *this == that*. Which is which, the docs do not specify at any point - in fact, you could say, the authors tried hard to write around that detail and leave it open. – O. R. Mapper Jun 19 '13 at 21:13
@O.R.Mapper I disagree. "Returns a negative integer, zero, or a positive integer **as this object is** less than, equal to, or greater than the specified object." The "as this object is" part maps integers to relations. – Sean Patrick Floyd Jun 20 '13 at 06:58
@SeanPatrickFloyd: I have always interpreted `compareTo` as you say, but now I'm finding myself in the situation of defending my assumption that things are as you say towards QA people who insist that the Java docs do not explicitly say "a negative integer means less than" etc. and thus any code that assumes so is incorrect. If there are any more explicit statements about that in the Java docs, I'd like to learn about them; I couldn't find any so far. – O. R. Mapper Jun 20 '13 at 07:02
@O.R.Mapper "and thus any code that assumes so is incorrect" ROFL! So the following are all incorrect: java.util.Tree(Map|Set), Collections.sort(), Arrays.sort() and many other places. Please! If you have to cope with guys like that then either they or you are in the wrong job. – Sean Patrick Floyd Jun 20 '13 at 08:05
In your warning you say "you should never rely on the return values of compareTo..." Why not? In what situations would compareTo yield something other than -1, 0, or 1? – kojow7 Nov 07 '17 at 18:15
1

@kojow I haven't come across such an implementation, but [the contract clearly says](https://docs.oracle.com/javase/8/docs/api/java/lang/Comparable.html#compareTo-T-): "Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object." – Sean Patrick Floyd Nov 07 '17 at 23:37
@kowjow7 System.out.println("alpha".compareTo("deta")); yields -3 – Aaron Dec 08 '20 at 21:30

score 55 · Answer 2 · answered Sep 22 '10 at 14:55

55

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

answered Sep 22 '10 at 14:55

Colin Hebert

91,525
15
160
151

1

This is perfect! – mvorisek Sep 23 '17 at 12:18
1

I use this numeric-only version to remember easily: `a.compareTo(b) = a - b`. – Crouching Kitten Feb 26 '20 at 22:07
1

@CrouchingKitten `a-b` should never be used in an implementation of compareTo() in real code, because it can (and will) overflow. – Clement Cherlin May 29 '20 at 11:55

score 34 · Answer 3 · answered Sep 26 '16 at 05:52

34

Answer in short: (search your situation)

1.compareTo(0) (return: 1)
1.compareTo(1) (return: 0)
0.comapreTo(1) (return: -1)

answered Sep 26 '16 at 05:52

user1012506

2,048
1
26
45

score 5 · Answer 4 · edited Apr 08 '13 at 06:26

5

take example if we want to compare "a" and "b", i.e ("a" == this)

negative int if a < b
if a == b
Positive int if a > b

edited Apr 08 '13 at 06:26

Anthon

69,918
32
186
246

answered Apr 08 '13 at 06:08

bhavesh

151
1
4

Michał Niklas · Answer 5 · 2010-09-23T09:27:42.993

3

It can be used for sorting, and 0 means "equal" while -1, and 1 means "less" and "more (greater)".

Any return value that is less than 0 means that left operand is lesser, and if value is bigger than 0 then left operand is bigger.

edited Sep 23 '10 at 09:27

answered Sep 22 '10 at 07:23

Michał Niklas

53,067
18
70
114

2

It's negative, positive and 0, not simply -1, 1 and 0 – Colin Hebert Sep 22 '10 at 15:02
Colin, there was -1, 0 and 1 in question. And yes, while some comparators return only one of those values, other can return any value, where negative means that left operand is smaller, zero means both operands are equal, and positive means left is bigger. Outside the Java land thats like `strcmp()` from C works. – Michał Niklas Sep 23 '10 at 09:25

score 2 · Answer 6 · edited Nov 17 '14 at 17:07

2

int x = thisObject.compareTo(anotherObject);

The compareTo() method returns an int with the following characteristics:

negative If thisObject < anotherObject
zero If thisObject == anotherObject
positive If thisObject > anotherObject

edited Nov 17 '14 at 17:07

fedorqui

275,237
103
548
598

answered Nov 17 '14 at 16:51

Artur Yolchyan

45
2

score 1 · Answer 7 · answered Aug 28 '20 at 14:17

1

System.out.println(A.compareTo(B)>0?"Yes":"No")

if the value of A>B it will return "Yes" or "No".

answered Aug 28 '20 at 14:17

Chaitanya Vibhu

11
1

1

Do you think your answer suits the question? – Prasanth Rajendran Aug 28 '20 at 14:24
1

Please add some explanation to your answer such that others can learn from it – Nico Haase Aug 28 '20 at 16:06

What do the return values of Comparable.compareTo mean in Java?

7 Answers7

Official Definition

My Version

Examples

Some additional points

Linked

Related