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

8261862: Expand discussion of rationale for BigDecimal equals/compareTo semantics

Browse source 
Reviewed-by: smarks, bpb
This commit is contained in:
Joe Darcy 2021-03-03 19:29:17 +00:00
parent 2d2ef08c0f
commit a11818528a
1 changed files with 19 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

27
src/java.base/share/classes/java/math/BigDecimal.java
View file

@ -212,13 +212,13 @@ import java.util.Objects;
* {@code NullPointerException} when passed a {@code null} object * {@code NullPointerException} when passed a {@code null} object
* reference for any input parameter. * reference for any input parameter.
* *
* @apiNote Care should be exercised if {@code BigDecimal} objects * @apiNote Care should be exercised if {@code BigDecimal} objects are
* are used as keys in a {@link java.util.SortedMap SortedMap} or * used as keys in a {@link java.util.SortedMap SortedMap} or elements
* elements in a {@link java.util.SortedSet SortedSet} since * in a {@link java.util.SortedSet SortedSet} since {@code
* {@code BigDecimal}'s <i>natural ordering</i> is <em>inconsistent * BigDecimal}'s <i>{@linkplain compareTo(BigDecimal) natural
* with equals</em>. See {@link Comparable}, {@link * ordering}</i> is <em>inconsistent with equals</em>. See {@link
* java.util.SortedMap} or {@link java.util.SortedSet} for more * Comparable}, {@link java.util.SortedMap} or {@link
* information. * java.util.SortedSet} for more information.
* *
* @see BigInteger * @see BigInteger
* @see MathContext * @see MathContext
@ -3141,7 +3141,18 @@ public class BigDecimal extends Number implements Comparable<BigDecimal> {
* compareTo}, this method considers two {@code BigDecimal} * compareTo}, this method considers two {@code BigDecimal}
* objects equal only if they are equal in value and * objects equal only if they are equal in value and
* scale. Therefore 2.0 is not equal to 2.00 when compared by this * scale. Therefore 2.0 is not equal to 2.00 when compared by this
* method. * method since the former has [{@code BigInteger}, {@code scale}]
* components equal to [20, 1] while the latter has components
* equal to [200, 2].
*
* @apiNote
* One example that shows how 2.0 and 2.00 are <em>not</em>
* substitutable for each other under some arithmetic operations
* are the two expressions:<br>
* {@code new BigDecimal("2.0" ).divide(BigDecimal.valueOf(3),
* HALF_UP)} which evaluates to 0.7 and <br>
* {@code new BigDecimal("2.00").divide(BigDecimal.valueOf(3),
* HALF_UP)} which evaluates to 0.67.
* *
* @param x {@code Object} to which this {@code BigDecimal} is * @param x {@code Object} to which this {@code BigDecimal} is
* to be compared. * to be compared.