archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 14:54:52 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8240632: Note differences between IEEE 754-2019 math lib special cases and java.lang.Math

Browse source 
Reviewed-by: bpb
This commit is contained in:
Joe Darcy 2021-02-08 21:50:55 +00:00
parent ace8f94616
commit 2fd8ed024b
5 changed files with 264 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

75
src/java.base/share/classes/java/lang/Math.java
View file

@ -1,5 +1,5 @@
/*
* Copyright (c) 1994, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -37,7 +37,7 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
* square root, and trigonometric functions.
*
* <p>Unlike some of the numeric methods of class
* {@code StrictMath}, all implementations of the equivalent
* {@link java.lang.StrictMath StrictMath}, all implementations of the equivalent
* functions of class {@code Math} are not defined to return the
* bit-for-bit same results. This relaxation permits
* better-performing implementations where strict reproducibility is
@ -99,6 +99,28 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
* occurs only with a specific minimum or maximum value and
* should be checked against the minimum or maximum as appropriate.
*
* <h2><a id=Ieee754RecommendedOps>IEEE 754 Recommended
* Operations</a></h2>
*
* The 2019 revision of the IEEE 754 floating-point standard includes
* a section of recommended operations and the semantics of those
* operations if they are included in a programming environment. The
* recommended operations present in this class include {@link sin
* sin}, {@link cos cos}, {@link tan tan}, {@link asin asin}, {@link
* acos acos}, {@link atan atan}, {@link exp exp}, {@link expm1
* expm1}, {@link log log}, {@link log10 log10}, {@link log1p log1p},
* {@link sinh sinh}, {@link cosh cosh}, {@link tanh tanh}, {@link
* hypot hypot}, and {@link pow pow}. (The {@link sqrt sqrt}
* operation is a required part of IEEE 754 from a different section
* of the standard.) The special case behavior of the recommended
* operations generally follows the guidance of the IEEE 754
* standard. However, the {@code pow} method defines different
* behavior for some arguments, as noted in its {@linkplain pow
* specification}. The IEEE 754 standard defines its operations to be
* correctly rounded, which is a more stringent quality of
* implementation condition than required for most of the methods in
* question that are also included in this class.
*
* @author Joseph D. Darcy
* @since 1.0
*/
@ -156,7 +178,9 @@ public final class Math {
/**
* Returns the trigonometric cosine of an angle. Special cases:
* <ul><li>If the argument is NaN or an infinity, then the
* result is NaN.</ul>
* result is NaN.
* <li>If the argument is zero, then the result is {@code 1.0}.
*</ul>
*
* <p>The computed result must be within 1 ulp of the exact result.
* Results must be semi-monotonic.
@ -209,7 +233,9 @@ public final class Math {
* Returns the arc cosine of a value; the returned angle is in the
* range 0.0 through <i>pi</i>. Special case:
* <ul><li>If the argument is NaN or its absolute value is greater
* than 1, then the result is NaN.</ul>
* than 1, then the result is NaN.
* <li>If the argument is {@code 1.0}, the result is positive zero.
* </ul>
*
* <p>The computed result must be within 1 ulp of the exact result.
* Results must be semi-monotonic.
@ -226,7 +252,11 @@ public final class Math {
* range -<i>pi</i>/2 through <i>pi</i>/2. Special cases:
* <ul><li>If the argument is NaN, then the result is NaN.
* <li>If the argument is zero, then the result is a zero with the
* same sign as the argument.</ul>
* same sign as the argument.
* <li>If the argument is {@linkplain Double#isInfinite infinite},
* then the result is the closest value to <i>pi</i>/2 with the
* same sign as the input.
* </ul>
*
* <p>The computed result must be within 1 ulp of the exact result.
* Results must be semi-monotonic.
@ -275,7 +305,9 @@ public final class Math {
* <li>If the argument is positive infinity, then the result is
* positive infinity.
* <li>If the argument is negative infinity, then the result is
* positive zero.</ul>
* positive zero.
* <li>If the argument is zero, then the result is {@code 1.0}.
* </ul>
*
* <p>The computed result must be within 1 ulp of the exact result.
* Results must be semi-monotonic.
@ -297,7 +329,10 @@ public final class Math {
* <li>If the argument is positive infinity, then the result is
* positive infinity.
* <li>If the argument is positive zero or negative zero, then the
* result is negative infinity.</ul>
* result is negative infinity.
* <li>If the argument is {@code 1.0}, then the result is positive
* zero.
* </ul>
*
* <p>The computed result must be within 1 ulp of the exact result.
* Results must be semi-monotonic.
@ -321,8 +356,10 @@ public final class Math {
* positive infinity.
* <li>If the argument is positive zero or negative zero, then the
* result is negative infinity.
* <li> If the argument is equal to 10<sup><i>n</i></sup> for
* integer <i>n</i>, then the result is <i>n</i>.
* <li>If the argument is equal to 10<sup><i>n</i></sup> for
* integer <i>n</i>, then the result is <i>n</i>. In particular,
* if the argument is {@code 1.0} (10<sup>0</sup>), then the
* result is positive zero.
* </ul>
*
* <p>The computed result must be within 1 ulp of the exact result.
@ -529,6 +566,15 @@ public final class Math {
* <p>The computed result must be within 2 ulps of the exact result.
* Results must be semi-monotonic.
*
* @apiNote
* For <i>y</i> with a positive sign and finite nonzero
* <i>x</i>, the exact mathematical value of {@code atan2} is
* equal to:
* <ul>
* <li>If <i>x</i> {@literal >} 0, atan(abs(<i>y</i>/<i>x</i>))
* <li>If <i>x</i> {@literal <} 0, &pi; - atan(abs(<i>y</i>/<i>x</i>))
* </ul>
*
* @param y the ordinate coordinate
* @param x the abscissa coordinate
* @return the <i>theta</i> component of the point
@ -660,6 +706,16 @@ public final class Math {
* <p>The computed result must be within 1 ulp of the exact result.
* Results must be semi-monotonic.
*
* @apiNote
* The special cases definitions of this method differ from the
* special case definitions of the IEEE 754 recommended {@code
* pow} operation for &plusmn;{@code 1.0} raised to an infinite
* power. This method treats such cases as indeterminate and
* specifies a NaN is returned. The IEEE 754 specification treats
* the infinite power as a large integer (large-magnitude
* floating-point numbers are numerically integers, specifically
* even integers) and therefore specifies {@code 1.0} be returned.
*
* @param a the base.
* @param b the exponent.
* @return the value {@code a}<sup>{@code b}</sup>.
@ -2113,6 +2169,7 @@ public final class Math {
* <li> If either argument is NaN and neither argument is infinite,
* then the result is NaN.
*
* <li> If both arguments are zero, the result is positive zero.
* </ul>
*
* <p>The computed result must be within 1 ulp of the exact