--- old/src/java.base/share/classes/java/math/BigDecimal.java 2016-05-24 12:25:27.888975460 -0700 +++ new/src/java.base/share/classes/java/math/BigDecimal.java 2016-05-24 12:25:27.536975466 -0700 @@ -55,7 +55,7 @@ * object to the operation. In either case, eight rounding * modes are provided for the control of rounding. Using the * integer fields in this class (such as {@link #ROUND_HALF_UP}) to - * represent rounding mode is largely obsolete; the enumeration values + * represent rounding mode is deprecated; the enumeration values * of the {@code RoundingMode} {@code enum}, (such as {@link * RoundingMode#HALF_UP}) should be used instead. * @@ -93,7 +93,7 @@ *
In general the rounding modes and precision setting determine * how operations return results with a limited number of digits when * the exact result has more digits (perhaps infinitely many in the - * case of division) than the number of digits returned. + * case of division and square root) than the number of digits returned. * * First, the * total number of digits to return is specified by the @@ -196,18 +196,19 @@ * {@code BigDecimal} value; for example [19, 2] is the * {@code BigDecimal} numerically equal to 0.19 having a scale of 2. * - *
Note: 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 natural ordering is inconsistent - * with equals. See {@link Comparable}, {@link - * java.util.SortedMap} or {@link java.util.SortedSet} for more - * information. * *
All methods and constructors for this class throw * {@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 natural ordering is inconsistent + * with equals. See {@link Comparable}, {@link + * java.util.SortedMap} or {@link java.util.SortedSet} for more + * information. + * * @see BigInteger * @see MathContext * @see RoundingMode @@ -377,10 +378,10 @@ * same sequence of characters as the {@link #BigDecimal(String)} * constructor, while allowing a sub-array to be specified. * - *
Note that if the sequence of characters is already available + * @implNote If the sequence of characters is already available * within a character array, using this constructor is faster than * converting the {@code char} array to string and using the - * {@code BigDecimal(String)} constructor . + * {@code BigDecimal(String)} constructor. * * @param in {@code char} array that is the source of characters. * @param offset first character in the array to inspect. @@ -401,14 +402,14 @@ * constructor, while allowing a sub-array to be specified and * with rounding according to the context settings. * - *
Note that if the sequence of characters is already available + * @implNote If the sequence of characters is already available * within a character array, using this constructor is faster than * converting the {@code char} array to string and using the * {@code BigDecimal(String)} constructor. * * @param in {@code char} array that is the source of characters. * @param offset first character in the array to inspect. - * @param len number of characters to consider.. + * @param len number of characters to consider. * @param mc the context to use. * @throws ArithmeticException if the result is inexact but the * rounding mode is {@code UNNECESSARY}. @@ -679,10 +680,10 @@ * same sequence of characters as the {@link #BigDecimal(String)} * constructor. * - *
Note that if the sequence of characters is already available + * @implNote If the sequence of characters is already available * as a character array, using this constructor is faster than * converting the {@code char} array to string and using the - * {@code BigDecimal(String)} constructor . + * {@code BigDecimal(String)} constructor. * * @param in {@code char} array that is the source of characters. * @throws NumberFormatException if {@code in} is not a valid @@ -700,10 +701,10 @@ * constructor and with rounding according to the context * settings. * - *
Note that if the sequence of characters is already available + * @implNote If the sequence of characters is already available * as a character array, using this constructor is faster than * converting the {@code char} array to string and using the - * {@code BigDecimal(String)} constructor . + * {@code BigDecimal(String)} constructor. * * @param in {@code char} array that is the source of characters. * @param mc the context to use. @@ -805,7 +806,7 @@ * "-0" [0,0] * * - *
Note: For values other than {@code float} and + * @apiNote For values other than {@code float} and * {@code double} NaN and ±Infinity, this constructor is * compatible with the values returned by {@link Float#toString} * and {@link Double#toString}. This is generally the preferred @@ -859,13 +860,13 @@ * This is because 0.1 cannot be represented exactly as a * {@code double} (or, for that matter, as a binary fraction of * any finite length). Thus, the value that is being passed - * in to the constructor is not exactly equal to 0.1, + * in to the constructor is not exactly equal to 0.1, * appearances notwithstanding. * *
Note: This is generally the preferred way to convert - * a {@code double} (or {@code float}) into a - * {@code BigDecimal}, as the value returned is equal to that - * resulting from constructing a {@code BigDecimal} from the - * result of using {@link Double#toString(double)}. + * @apiNote This is generally the preferred way to convert a + * {@code double} (or {@code float}) into a {@code BigDecimal}, as + * the value returned is equal to that resulting from constructing + * a {@code BigDecimal} from the result of using {@link + * Double#toString(double)}. * * @param val {@code double} to convert to a {@code BigDecimal}. * @return a {@code BigDecimal} whose value is equal to or approximately @@ -1896,7 +1899,7 @@ * *
The remainder is given by * {@code this.subtract(this.divideToIntegralValue(divisor).multiply(divisor))}. - * Note that this is not the modulo operation (the result can be + * Note that this is not the modulo operation (the result can be * negative). * * @param divisor value by which this {@code BigDecimal} is to be divided. @@ -2037,6 +2040,7 @@ * {@code (mc.getRoundingMode()==RoundingMode.UNNECESSARY}) and * the exact result cannot fit in {@code mc.getPrecision()} * digits. + * @see BigInteger#sqrt() * @since 9 */ public BigDecimal sqrt(MathContext mc) { @@ -2694,8 +2698,8 @@ * in this case, the specified rounding mode is applied to the * division. * - *
Note that since BigDecimal objects are immutable, calls of
- * this method do not result in the original object being
+ * @apiNote Since BigDecimal objects are immutable, calls of
+ * this method do not result in the original object being
* modified, contrary to the usual convention of having methods
* named setX
mutate field {@code X}.
* Instead, {@code setScale} returns an object with the proper
@@ -2727,8 +2731,8 @@
* in this case, the specified rounding mode is applied to the
* division.
*
- *
Note that since BigDecimal objects are immutable, calls of
- * this method do not result in the original object being
+ * @apiNote Since BigDecimal objects are immutable, calls of
+ * this method do not result in the original object being
* modified, contrary to the usual convention of having methods
* named setX
mutate field {@code X}.
* Instead, {@code setScale} returns an object with the proper
@@ -2822,8 +2826,8 @@
* versions of {@code setScale}, but saves the caller the trouble
* of specifying a rounding mode in cases where it is irrelevant.
*
- *
Note that since {@code BigDecimal} objects are immutable,
- * calls of this method do not result in the original
+ * @apiNote Since {@code BigDecimal} objects are immutable,
+ * calls of this method do not result in the original
* object being modified, contrary to the usual convention of
* having methods named setX
mutate field
* {@code X}. Instead, {@code setScale} returns an
@@ -3091,7 +3095,7 @@
/**
* Returns the hash code for this {@code BigDecimal}. Note that
* two {@code BigDecimal} objects that are numerically equal but
- * differ in scale (like 2.0 and 2.00) will generally not
+ * differ in scale (like 2.0 and 2.00) will generally not
* have the same hash code.
*
* @return hash code for this {@code BigDecimal}.
@@ -3342,7 +3346,7 @@
* Converts this {@code BigDecimal} to a {@code BigInteger}.
* This conversion is analogous to the
* narrowing primitive conversion from {@code double} to
- * {@code long} as defined in section 5.1.3 of
+ * {@code long} as defined in
* The Java™ Language Specification:
* any fractional part of this
* {@code BigDecimal} will be discarded. Note that this
@@ -3354,6 +3358,7 @@
* {@link #toBigIntegerExact()} method.
*
* @return this {@code BigDecimal} converted to a {@code BigInteger}.
+ * @jls 5.1.3 Narrowing Primitive Conversion
*/
public BigInteger toBigInteger() {
// force to an integer, quietly
@@ -3379,7 +3384,7 @@
* Converts this {@code BigDecimal} to a {@code long}.
* This conversion is analogous to the
* narrowing primitive conversion from {@code double} to
- * {@code short} as defined in section 5.1.3 of
+ * {@code short} as defined in
* The Java™ Language Specification:
* any fractional part of this
* {@code BigDecimal} will be discarded, and if the resulting
@@ -3390,6 +3395,7 @@
* as return a result with the opposite sign.
*
* @return this {@code BigDecimal} converted to a {@code long}.
+ * @jls 5.1.3 Narrowing Primitive Conversion
*/
@Override
public long longValue(){
@@ -3448,7 +3454,7 @@
* Converts this {@code BigDecimal} to an {@code int}.
* This conversion is analogous to the
* narrowing primitive conversion from {@code double} to
- * {@code short} as defined in section 5.1.3 of
+ * {@code short} as defined in
* The Java™ Language Specification:
* any fractional part of this
* {@code BigDecimal} will be discarded, and if the resulting
@@ -3459,6 +3465,7 @@
* value as well as return a result with the opposite sign.
*
* @return this {@code BigDecimal} converted to an {@code int}.
+ * @jls 5.1.3 Narrowing Primitive Conversion
*/
@Override
public int intValue() {
@@ -3531,7 +3538,7 @@
* Converts this {@code BigDecimal} to a {@code float}.
* This conversion is similar to the
* narrowing primitive conversion from {@code double} to
- * {@code float} as defined in section 5.1.3 of
+ * {@code float} as defined in
* The Java™ Language Specification:
* if this {@code BigDecimal} has too great a
* magnitude to represent as a {@code float}, it will be
@@ -3542,6 +3549,7 @@
* value.
*
* @return this {@code BigDecimal} converted to a {@code float}.
+ * @jls 5.1.3 Narrowing Primitive Conversion
*/
@Override
public float floatValue(){
@@ -3575,7 +3583,7 @@
* Converts this {@code BigDecimal} to a {@code double}.
* This conversion is similar to the
* narrowing primitive conversion from {@code double} to
- * {@code float} as defined in section 5.1.3 of
+ * {@code float} as defined
* The Java™ Language Specification:
* if this {@code BigDecimal} has too great a
* magnitude represent as a {@code double}, it will be
@@ -3586,6 +3594,7 @@
* value.
*
* @return this {@code BigDecimal} converted to a {@code double}.
+ * @jls 5.1.3 Narrowing Primitive Conversion
*/
@Override
public double doubleValue(){