What does the word "equals" mean in Java API?

Question

I'm not sure anyone will know the answer to this question, unless you are responsible for writing the Jave API, but when the Java API says "equals", does it always mean that a.equals(b) evaluates to true, or sometime does it mean a == b is true? I have recently extended a class and wondered if I needed to override a method depending on where or not it used == or .equals. Specifically, I extended javafx.beans.binding.ObjectExpression and was curious about the .isEqualTo(Object other) method. I checked the source (here) and found that this method uses .equals for comparison. I'm curious if I can be confident that when I read things like

"Creates a new BooleanExpression that holds true if this ObjectExpression is equal to a constant value."

that the method is not using the == operator. Although, as I think of it, the API can't possibly mean .equals either, since (for example)

String constant = "constant";
ObjectExpress<String> stringExpression = new MyStringExpression("constant");

constant.equals(stringExpression)

will always evaluates to false. So maybe my question should be "when the API says 'equals', does it always refer to the most reasonable way to apply .equal or sometime does it refer to the analogous way to apply ==?"

EDIT

I think based on the answers I should clarify: this is not a question about the difference between == and .equal. It is about to which the Java API is referring when it uses the English word "equals".

`==` compares references, always. Usually when we say "equals", we refer to the content, not the reference. — Maroun, Feb 25 '14 at 08:50
Good API documentation should not call `==` "equal", compare http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/cache/CacheBuilder.html#weakKeys%28%29 — zapl, Feb 25 '14 at 09:12

score 2 · Answer 1 · answered Feb 25 '14 at 09:12

It's clear that you do understand the difference between equals() and ==. So your question is rather philosophical :)

Generally, many APIs use "equals to" in the meaning of equals() and "is the same as" in the meaning of ==. E.g. JUnit has assertion method assertEquals() and assertSame().

However, use your common sense and analyze the language of the doucmentation. Notice in your quoted sentence from API the usage of the indefinite article:

"Creates a new BooleanExpression that holds true if this ObjectExpression is equal to a constant value."

"a constant value" clearly means any constant value, not the same value as the "constant" value. So it is clear that this cannot mean the same as constant.equals(stringExpression).

So take it in this way: when documentation says "equals", take it that it relates to the content of the variable, not to its reference. But use common sense and read the sentence as a whole :)

Does it answer your question? :P

score 1 · Answer 2 · answered Feb 25 '14 at 08:51

1

does it always mean that a.equals(b) evaluates to true, or sometime does it mean a == b is true? when the API says 'equals', does it always refer to the most reasonable way to apply .equal or sometime does it refer to the analogous way to apply ==?"

It's about overriding equals() method, In java, only += operator overloaded, other operators can't be overloaded means, you can't override ==

answered Feb 25 '14 at 08:51

Abimaran Kugathasan

31,165
11
75
105

The guy asking the question *does* understand this. You are right, but he has not asked about *this*. – Honza Zidek Feb 25 '14 at 09:18
1

+1 `+` is also overloaded for Strings, but this is defined in the language and cannot be changed by the programmer. – Peter Lawrey Feb 25 '14 at 09:20

score 1 · Answer 3 · answered Feb 25 '14 at 08:58

When writing an API-doc when using the term "equal" this should usually mean "equal in terms of the equals()-method". If it really does depends on the thoroughness of the writer of the documentation, but in the official API-docs I would always take as having this meaning.

For your question "can it also mean ==": it can in the way that Object's equals()-method just checks for reference-identity, that is it checks using ==.

GuyT · Answer 4 · 2014-02-25T09:01:01.370

If you use .equals it will compare the value. By using == you are comparing the reference and these doesn't have to be the same even if your values are the same.

See following website for a full explanation: http://www.javabeat.net/what-is-difference-between-equals-and/

I've copied a part of his example:

s1 = new String("abc");
s2 = new String("abc");

Now, if you use the equals() method to check for their equivalence as

if(s1.equals(s2))
     System.out.println("s1.equals(s2) is TRUE");
else
     System.out.println("s1.equals(s2) is FALSE");

You will get the output as TRUE as the equals() method check for the content equality. Lets check the == operator..

if(s1==s2)
     System.out.printlln("s1==s2 is TRUE");
   else
     System.out.println("s1==s2 is FALSE");

Now you will get the FALSE as output because both s1 and s2 are pointing to two different objects even though both of them share the same string content. It is because of new String() everytime a new object is created.

Again, the guy asking the question *does* understand this. You are right, but he has not asked about *this*. — Honza Zidek, Feb 25 '14 at 09:19

score 0 · Answer 5 · answered Feb 25 '14 at 09:21

When some one creates a java class it inherit boolean equals(Object o) method from class 'Object', as all user defined class when not extending any other class extends class Object implicitly.

When this class is instantiated using new operator the equality of this objects are achieved by using this underline formula.

    return (this == obj);

Hence it will return true if and only if both object refers to the same object on the heap i.e (a == b) = true

    class Abc{}
    Abc a = new Abc();
    Abc b = a;
    a==b //(true)
    a.equals(b) //(true)

And suppose they are instance of same class but are two different object than

   class Abc{}
   Abc a = new Abc();
   Abc b = new Abc();
   a==b; //(false)
   a.equals(b); //(false)

But when an class created overrides this equals method then this equality is evaluated using the new formula provided while overriding it. for example .equals object override by java.util.Date

    public boolean equals(Object obj) {
            return obj instanceof Date && getTime() == ((Date) obj).getTime();
     }

This will return true if and only both Date object have equal value returned by getTime() method.

Hope this helps. Feel free to ask further questions if any doubt.

One nasty gotcha with `equals` is that class objects of mutable types may be used either as values or entities, and references to such class objects may either encapsulate their values or their identities. To know whether two references should be considered "equal", one must know what they encapsulate, but there's no standard way by which instances of a class objects can be told what kind of equality they should use, nor for collections to know what kind of equality to ask for in their contents. — supercat, Feb 26 '14 at 00:17

What does the word "equals" mean in Java API?

5 Answers5