RFR: JDK-8257086: Clarify differences between {Float, Double}.equals and ==

[Joe Darcy]

Hi Stuart,

On 1/28/2021 7:19 PM, Stuart Marks wrote:
> On Thu, 28 Jan 2021 07:15:05 GMT, Joe Darcy <darcy at openjdk.org> wrote:
>
>>> Great, let me know if you'd like me to provide some text for any particular topics in this area.
>>>
>>> Great, let me know if you'd like me to provide some text for any particular topics in this area.
>> Before sending out another iteration in code, there the draft javadoc text of a discussion at the end of the class-level discussion of java.lang.Double:
>>

[snip]

>>
>> Comments?
>>
>> Thanks,
> I took the liberty of making an editing pass over the proposed text. Along with a few editorial and markup adjustments, the key changes are as follows:
>
> 1) I moved discussion of interaction with Set and Map to the end, after all the issues have been set up.
>
> 2) I added the concept of substitution alongside the equivalence relation. AFAIK substitution (or substitutability) is not part of an equivalence relation, but it seems that in many systems, equivalence implies substitutability. Of course, the point is that it _doesn't_ apply for -0.0 and +0.0.

Yes; substitutability was an implicit concept in the earlier write-up; 
it is an improvement to call it out my name.

I'll work on integrating this version into an update of the PR with 
references from the equals and compareTo methods, etc.

Thanks,

-Joe



>
> -------------
>
> PR: https://git.openjdk.java.net/jdk/pull/1699