JDK 15 RFR of JDK-8240624: Note mapping of RoundingMode constants to equivalent IEEE 754-2019 policy
Joe Darcy
joe.darcy at oracle.com
Thu Mar 5 21:45:49 UTC 2020
Hello,
Where such a mapping exists, it would be helpful to tie the policies
represented by various RoundingMode constants to the equivalent rounding
attribute defined by IEEE 754-2019, the latest version of the
floating-point standard:
JDK-8240624: Note mapping of RoundingMode constants to equivalent
IEEE 754-2019 policy
http://cr.openjdk.java.net/~darcy/8240624.0/
Please review the patch below; I'll update the file copyright year
before pushing.
Thanks,
-Joe
--- old/src/java.base/share/classes/java/math/RoundingMode.java 2020-03-05 13:44:23.971037000 -0800
+++ new/src/java.base/share/classes/java/math/RoundingMode.java 2020-03-05 13:44:23.647037000 -0800
@@ -87,6 +87,12 @@
* ({@link BigDecimal#ROUND_UP}, {@link BigDecimal#ROUND_DOWN},
* etc. ).
*
+ * @apiNote
+ * Five of the rounding modes defined in this class correspond to
+ * rounding direction attributes defined in IEEE 754-2019. Where
+ * present, this correspondence will be noted in the documentation of
+ * the particular constant.
+ *
* @see BigDecimal
* @see MathContext
* @author Josh Bloch
@@ -130,7 +136,9 @@
* 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
+ * attribute roundTowardZero.
+ *
*<p>Example:
*<table class="striped">
* <caption>Rounding mode DOWN Examples</caption>
@@ -159,6 +167,8 @@
* 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
+ * attribute roundTowardPositive.
*
*<p>Example:
*<table class="striped">
@@ -188,6 +198,8 @@
* 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
+ * attribute roundTowardNegative.
*
*<p>Example:
*<table class="striped">
@@ -219,6 +231,8 @@
* fraction is ≥ 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
+ * attribute roundTiesToAway.
*
*<p>Example:
*<table class="striped">
@@ -286,6 +300,8 @@
* 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
+ * attribute roundTiesToEven.
*
*<p>Example:
*<table class="striped">
More information about the core-libs-dev
mailing list