Skip to content
Permalink
Browse files
8261862: Expand discussion of rationale for BigDecimal equals/compare…
…To semantics

Reviewed-by: smarks, bpb
  • Loading branch information
jddarcy committed Mar 3, 2021
1 parent 2d2ef08 commit a11818528a99a50f0900d3803362607d40c6b9f7
Showing 1 changed file with 19 additions and 8 deletions.
@@ -212,13 +212,13 @@
* {@code NullPointerException} when passed a {@code null} object
* reference for any input parameter.
*
* @apiNote Care should be exercised if {@code BigDecimal} objects
* are used as keys in a {@link java.util.SortedMap SortedMap} or
* elements in a {@link java.util.SortedSet SortedSet} since
* {@code BigDecimal}'s <i>natural ordering</i> is <em>inconsistent
* with equals</em>. See {@link Comparable}, {@link
* java.util.SortedMap} or {@link java.util.SortedSet} for more
* information.
* @apiNote Care should be exercised if {@code BigDecimal} objects are
* used as keys in a {@link java.util.SortedMap SortedMap} or elements
* in a {@link java.util.SortedSet SortedSet} since {@code
* BigDecimal}'s <i>{@linkplain compareTo(BigDecimal) natural
* ordering}</i> is <em>inconsistent with equals</em>. See {@link
* Comparable}, {@link java.util.SortedMap} or {@link
* java.util.SortedSet} for more information.
*
* @see BigInteger
* @see MathContext
@@ -3141,7 +3141,18 @@ else if (ys != INFLATED)
* compareTo}, this method considers two {@code BigDecimal}
* objects equal only if they are equal in value and
* 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
* to be compared.

0 comments on commit a118185

Please sign in to comment.