RFD: "equal" vs "equivalent" in Float.NaN, Double.NaN

[Joseph D. Darcy]

On 11/1/2024 1:19 PM, Eirik Bjørsnøs wrote:
> On Fri, Nov 1, 2024 at 8:42 PM Joseph D. Darcy <joe.darcy at oracle.com> 
> wrote:
>
>     A few releases back, a discussion of "quality, equivalence, and
>     comparison of floating-point values" was added to java.lang.Double:
>
>     https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/lang/Double.html#equivalenceRelation
>
>     That note discusses the topics in question.
>
> Thanks Joe, that's exactly what I was missing. Saying "equivalent to" 
> without defining the equivalence relation seems to leave room for 
> confusion.
>
> I see the API note of Float/Double::equals link to this note. Do you 
> think it would be useful / worthwhile to add a @linkplain from the NaN 
> descriptions as well, like this?
>
>      /**
>       * A constant holding a Not-a-Number (NaN) value of type
> -     * {@code float}.  It is equivalent to the value returned by
> -     * {@code Float.intBitsToFloat(0x7fc00000)}.
> +     * {@code float}.  It is {@linkplain Double##equivalenceRelation 
> equivalent}
> +     * to the value returned by {@code Float.intBitsToFloat(0x7fc00000)}.
>       */
>      public static final float NaN = 0.0f / 0.0f;
>
> Cheers,
> Eirik.

That would be a reasonable enhancement to the docs; thanks,

-Joe

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20241107/4da63c58/attachment-0001.htm>