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

8261123: Augment discussion of equivalence classes in Object.equals and comparison methods

Browse source 
Reviewed-by: bpb, smarks, rriggs
This commit is contained in:
Joe Darcy 2021-02-17 01:08:39 +00:00
parent 2677f6f47d
commit d547e1a847
4 changed files with 135 additions and 99 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -1,5 +1,5 @@
/*
* Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1996, 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
@ -63,33 +63,38 @@ import java.util.Objects;
* <p>When a {@code MathContext} object is supplied with a precision
* setting of 0 (for example, {@link MathContext#UNLIMITED}),
* arithmetic operations are exact, as are the arithmetic methods
* which take no {@code MathContext} object. (This is the only
* behavior that was supported in releases prior to 5.) As a
* corollary of computing the exact result, the rounding mode setting
* of a {@code MathContext} object with a precision setting of 0 is
* not used and thus irrelevant. In the case of divide, the exact
* quotient could have an infinitely long decimal expansion; for
* example, 1 divided by 3. If the quotient has a nonterminating
* decimal expansion and the operation is specified to return an exact
* result, an {@code ArithmeticException} is thrown. Otherwise, the
* exact result of the division is returned, as done for other
* operations.
* which take no {@code MathContext} object. As a corollary of
* computing the exact result, the rounding mode setting of a {@code
* MathContext} object with a precision setting of 0 is not used and
* thus irrelevant. In the case of divide, the exact quotient could
* have an infinitely long decimal expansion; for example, 1 divided
* by 3. If the quotient has a nonterminating decimal expansion and
* the operation is specified to return an exact result, an {@code
* ArithmeticException} is thrown. Otherwise, the exact result of the
* division is returned, as done for other operations.
*
* <p>When the precision setting is not 0, the rules of
* {@code BigDecimal} arithmetic are broadly compatible with selected
* modes of operation of the arithmetic defined in ANSI X3.274-1996
* and ANSI X3.274-1996/AM 1-2000 (section 7.4). Unlike those
* standards, {@code BigDecimal} includes many rounding modes, which
* were mandatory for division in {@code BigDecimal} releases prior
* to 5. Any conflicts between these ANSI standards and the
* {@code BigDecimal} specification are resolved in favor of
* {@code BigDecimal}.
* <p>When the precision setting is not 0, the rules of {@code
* BigDecimal} arithmetic are broadly compatible with selected modes
* of operation of the arithmetic defined in ANSI X3.274-1996 and ANSI
* X3.274-1996/AM 1-2000 (section 7.4). Unlike those standards,
* {@code BigDecimal} includes many rounding modes. Any conflicts
* between these ANSI standards and the {@code BigDecimal}
* specification are resolved in favor of {@code BigDecimal}.
*
* <p>Since the same numerical value can have different
* representations (with different scales), the rules of arithmetic
* and rounding must specify both the numerical result and the scale
* used in the result's representation.
*
* The different representations of the same numerical value are
* called members of the same <i>cohort</i>. The {@linkplain
* compareTo(BigDecimal) natural order} of {@code BigDecimal}
* considers members of the same cohort to be equal to each other. In
* contrast, the {@link equals equals} method requires both the
* numerical value and representation to be the same for equality to
* hold. The results of methods like {@link scale} and {@link
* unscaledValue} will differ for numerically equal values with
* different representations.
*
* <p>In general the rounding modes and precision setting determine
* how operations return results with a limited number of digits when
@ -3040,16 +3045,21 @@ public class BigDecimal extends Number implements Comparable<BigDecimal> {
// Comparison Operations
/**
* Compares this {@code BigDecimal} with the specified
* Compares this {@code BigDecimal} numerically with the specified
* {@code BigDecimal}. Two {@code BigDecimal} objects that are
* equal in value but have a different scale (like 2.0 and 2.00)
* are considered equal by this method. This method is provided
* in preference to individual methods for each of the six boolean
* comparison operators ({@literal <}, ==,
* {@literal >}, {@literal >=}, !=, {@literal <=}). The
* suggested idiom for performing these comparisons is:
* {@code (x.compareTo(y)} &lt;<i>op</i>&gt; {@code 0)}, where
* are considered equal by this method. Such values are in the
* same <i>cohort</i>.
*
* This method is provided in preference to individual methods for
* each of the six boolean comparison operators ({@literal <}, ==,
* {@literal >}, {@literal >=}, !=, {@literal <=}). The suggested
* idiom for performing these comparisons is: {@code
* (x.compareTo(y)} &lt;<i>op</i>&gt; {@code 0)}, where
* &lt;<i>op</i>&gt; is one of the six comparison operators.
* @apiNote
* Note: this class has a natural ordering that is inconsistent with equals.
*
* @param val {@code BigDecimal} to which this {@code BigDecimal} is
* to be compared.
@ -3125,12 +3135,12 @@ public class BigDecimal extends Number implements Comparable<BigDecimal> {
}
/**
* Compares this {@code BigDecimal} with the specified
* {@code Object} for equality. Unlike {@link
* #compareTo(BigDecimal) compareTo}, this method considers two
* {@code BigDecimal} objects equal only if they are equal in
* value and scale (thus 2.0 is not equal to 2.00 when compared by
* this method).
* Compares this {@code BigDecimal} with the specified {@code
* Object} for equality. Unlike {@link #compareTo(BigDecimal)
* 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.
*
* @param x {@code Object} to which this {@code BigDecimal} is
* to be compared.