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

8273346: Expand library mappings to IEEE 754 operations

Browse source 
Reviewed-by: bpb
This commit is contained in:
Joe Darcy 2022-06-07 16:13:42 +00:00
parent 96641c0c42
commit 5d4ea9b954
4 changed files with 156 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

42
src/java.base/share/classes/java/math/RoundingMode.java
View file

@ -39,6 +39,21 @@ package java.math;
* considered as a numerical value, the discarded fraction could have
* an absolute value greater than one.
*
* <p>More generally, a rounding policy defines a mapping from the
* real numbers to a subset of representable values. In the case of
* {@link BigDecimal}, the representable values are a function of the
* {@linkplain MathContext#getPrecision() precision} being used in the
* computation. Assuming the mathematical result is within the
* exponent range of {@code BigDecimal}, the mathematical result will
* be exactly representable in the result precision or will fall
* between two adjacent representable values. In the case of falling
* between two representable values, the rounding policy determines
* which of those two bracketing values is the result. For in-range
* real numbers, for a given set of representable values, a rounding
* policy maps a continuous segment of the real number line to a
* single representable value where the real number numerically equal
* to a representable value is mapped to that value.
*
* <p>Each rounding mode description includes a table listing how
* different two-digit decimal values would round to a one digit
* decimal value under the rounding mode in question. The result
@ -90,7 +105,7 @@ package java.math;
* @apiNote
* Five of the rounding modes declared in this class correspond to
* rounding-direction attributes defined in the <cite>IEEE Standard
* for Floating-Point Arithmetic</cite>, IEEE 754-2019. Where present,
* for Floating-Point Arithmetic</cite>. Where present,
* this correspondence will be noted in the documentation of the
* particular constant.
*
@ -98,6 +113,7 @@ package java.math;
* @see MathContext
* @see <a href="https://standards.ieee.org/ieee/754/6210/">
* <cite>IEEE Standard for Floating-Point Arithmetic</cite></a>
* @jls 15.4 Floating-point Expressions
*
* @author Josh Bloch
* @author Mike Cowlishaw
@ -140,7 +156,13 @@ public enum RoundingMode {
* Rounding mode to round towards zero. Never increments the digit
* prior to a discarded fraction (i.e., truncates). Note that this
* rounding mode never increases the magnitude of the calculated value.
* This mode corresponds to the IEEE 754-2019 rounding-direction
*
* @apiNote
* This rounding mode is analogous to the rounding policy used
* for the {@code float} and {@code double} operators
* remainder and conversion to an integer value (JLS {@jls
* 15.4}).
* This mode corresponds to the IEEE 754 rounding-direction
* attribute roundTowardZero.
*
*<p>Example:
@ -171,7 +193,7 @@ public enum RoundingMode {
* result is positive, behaves as for {@code RoundingMode.UP};
* if negative, behaves as for {@code RoundingMode.DOWN}. Note
* that this rounding mode never decreases the calculated value.
* This mode corresponds to the IEEE 754-2019 rounding-direction
* This mode corresponds to the IEEE 754 rounding-direction
* attribute roundTowardPositive.
*
*<p>Example:
@ -202,7 +224,7 @@ public enum RoundingMode {
* result is positive, behave as for {@code RoundingMode.DOWN};
* if negative, behave as for {@code RoundingMode.UP}. Note that
* this rounding mode never increases the calculated value.
* This mode corresponds to the IEEE 754-2019 rounding-direction
* This mode corresponds to the IEEE 754 rounding-direction
* attribute roundTowardNegative.
*
*<p>Example:
@ -235,7 +257,7 @@ public enum RoundingMode {
* fraction is &ge; 0.5; otherwise, behaves as for
* {@code RoundingMode.DOWN}. Note that this is the rounding
* mode commonly taught at school.
* This mode corresponds to the IEEE 754-2019 rounding-direction
* This mode corresponds to the IEEE 754 rounding-direction
* attribute roundTiesToAway.
*
*<p>Example:
@ -297,14 +319,16 @@ public enum RoundingMode {
* towards the even neighbor. Behaves as for
* {@code RoundingMode.HALF_UP} if the digit to the left of the
* discarded fraction is odd; behaves as for
* {@code RoundingMode.HALF_DOWN} if it's even. Note that this
* {@code RoundingMode.HALF_DOWN} if it's even.
* @apiNote
* This
* is the rounding mode that statistically minimizes cumulative
* error when applied repeatedly over a sequence of calculations.
* It is sometimes known as {@literal "Banker's rounding,"} and is
* chiefly used in the USA. This rounding mode is analogous to
* the rounding policy used for {@code float} and {@code double}
* arithmetic in Java.
* This mode corresponds to the IEEE 754-2019 rounding-direction
* the rounding policy used for most {@code float} and {@code double}
* arithmetic operators in Java (JLS {@jls 15.4}).
* This mode corresponds to the IEEE 754 rounding-direction
* attribute roundTiesToEven.
*
*<p>Example: