am 6cb5da25: am ce7dd45a: Fix the BigDecimal documentation to not be a copy & paste of the BigInteger documentation.
* commit '6cb5da25729fe849700e962782811ee6166ed7a6':
Fix the BigDecimal documentation to not be a copy & paste of the BigInteger documentation.
diff --git a/luni/src/main/java/java/math/BigDecimal.java b/luni/src/main/java/java/math/BigDecimal.java
index 6b716bc..013809d 100644
--- a/luni/src/main/java/java/math/BigDecimal.java
+++ b/luni/src/main/java/java/math/BigDecimal.java
@@ -25,18 +25,12 @@
import libcore.math.MathUtils;
/**
- * This class represents immutable integer numbers of arbitrary length. Large
- * numbers are typically used in security applications and therefore BigIntegers
- * offer dedicated functionality like the generation of large prime numbers or
- * the computation of modular inverse.
- * <p>
- * Since the class was modeled to offer all the functionality as the {@link Integer}
- * class does, it provides even methods that operate bitwise on a two's
- * complement representation of large integers. Note however that the
- * implementations favors an internal representation where magnitude and sign
- * are treated separately. Hence such operations are inefficient and should be
- * discouraged. In simple words: Do NOT implement any bit fields based on
- * BigInteger.
+ * An immutable arbitrary-precision signed decimal.
+ *
+ * <p>A value is represented by an arbitrary-precision "unscaled value" and a signed 32-bit "scale",
+ * combined thus: {@code unscaled * 10<sup>-scale</sup>}. See {@link #unscaledValue} and {@link #scale}.
+ *
+ * <p>Most operations allow you to supply a {@link MathContext} to specify a desired rounding mode.
*/
public class BigDecimal extends Number implements Comparable<BigDecimal>, Serializable {
@@ -423,9 +417,6 @@
* Constructs a new {@code BigDecimal} instance from a string
* representation.
*
- * @param val
- * string containing the string representation of this {@code
- * BigDecimal}.
* @throws NumberFormatException
* if {@code val} does not contain a valid string representation
* of a big decimal.
@@ -439,9 +430,6 @@
* representation. The result is rounded according to the specified math
* context.
*
- * @param val
- * string containing the string representation of this {@code
- * BigDecimal}.
* @param mc
* rounding mode and precision for the result of this operation.
* @throws NumberFormatException
@@ -554,10 +542,6 @@
/**
* Constructs a new {@code BigDecimal} instance from the given big integer
* {@code val}. The scale of the result is {@code 0}.
- *
- * @param val
- * {@code BigInteger} value to be converted to a {@code
- * BigDecimal} instance.
*/
public BigDecimal(BigInteger val) {
this(val, 0);
@@ -567,9 +551,6 @@
* Constructs a new {@code BigDecimal} instance from the given big integer
* {@code val}. The scale of the result is {@code 0}.
*
- * @param val
- * {@code BigInteger} value to be converted to a {@code
- * BigDecimal} instance.
* @param mc
* rounding mode and precision for the result of this operation.
* @throws ArithmeticException
@@ -585,13 +566,8 @@
/**
* Constructs a new {@code BigDecimal} instance from a given unscaled value
* {@code unscaledVal} and a given scale. The value of this instance is
- * {@code unscaledVal} 10^(-{@code scale}).
+ * {@code unscaledVal * 10<sup>-scale</sup>}).
*
- * @param unscaledVal
- * {@code BigInteger} representing the unscaled value of this
- * {@code BigDecimal} instance.
- * @param scale
- * scale of this {@code BigDecimal} instance.
* @throws NullPointerException
* if {@code unscaledVal == null}.
*/
@@ -606,14 +582,9 @@
/**
* Constructs a new {@code BigDecimal} instance from a given unscaled value
* {@code unscaledVal} and a given scale. The value of this instance is
- * {@code unscaledVal} 10^(-{@code scale}). The result is rounded according
+ * {@code unscaledVal * 10<sup>-scale</sup>). The result is rounded according
* to the specified math context.
*
- * @param unscaledVal
- * {@code BigInteger} representing the unscaled value of this
- * {@code BigDecimal} instance.
- * @param scale
- * scale of this {@code BigDecimal} instance.
* @param mc
* rounding mode and precision for the result of this operation.
* @throws ArithmeticException
@@ -692,16 +663,8 @@
/**
* Returns a new {@code BigDecimal} instance whose value is equal to {@code
- * unscaledVal} 10^(-{@code scale}). The scale of the result is {@code
+ * unscaledVal * 10<sup>-scale</sup>}). The scale of the result is {@code
* scale}, and its unscaled value is {@code unscaledVal}.
- *
- * @param unscaledVal
- * unscaled value to be used to construct the new {@code
- * BigDecimal}.
- * @param scale
- * scale to be used to construct the new {@code BigDecimal}.
- * @return {@code BigDecimal} instance with the value {@code unscaledVal}*
- * 10^(-{@code unscaledVal}).
*/
public static BigDecimal valueOf(long unscaledVal, int scale) {
if (scale == 0) {
@@ -1625,17 +1588,14 @@
}
/**
- * Returns a new {@code BigDecimal} whose value is {@code this ^ n}. The
- * scale of the result is {@code n} times the scales of {@code this}.
- * <p>
- * {@code x.pow(0)} returns {@code 1}, even if {@code x == 0}.
- * <p>
- * Implementation Note: The implementation is based on the ANSI standard
+ * Returns a new {@code BigDecimal} whose value is {@code this<sup>n</sup>}. The
+ * scale of the result is {@code n * this.scale()}.
+ *
+ * <p>{@code x.pow(0)} returns {@code 1}, even if {@code x == 0}.
+ *
+ * <p>Implementation Note: The implementation is based on the ANSI standard
* X3.274-1996 algorithm.
*
- * @param n
- * exponent to which {@code this} is raised.
- * @return {@code this ^ n}.
* @throws ArithmeticException
* if {@code n < 0} or {@code n > 999999999}.
*/
@@ -1653,17 +1613,14 @@
}
/**
- * Returns a new {@code BigDecimal} whose value is {@code this ^ n}. The
+ * Returns a new {@code BigDecimal} whose value is {@code this<sup>n</sup>}. The
* result is rounded according to the passed context {@code mc}.
- * <p>
- * Implementation Note: The implementation is based on the ANSI standard
+ *
+ * <p>Implementation Note: The implementation is based on the ANSI standard
* X3.274-1996 algorithm.
*
- * @param n
- * exponent to which {@code this} is raised.
* @param mc
* rounding mode and precision for the result of this operation.
- * @return {@code this ^ n}.
* @throws ArithmeticException
* if {@code n < 0} or {@code n > 999999999}.
*/
@@ -1787,7 +1744,8 @@
*
* @return {@code -1} if {@code this < 0},
* {@code 0} if {@code this == 0},
- * {@code 1} if {@code this > 0}. */
+ * {@code 1} if {@code this > 0}.
+ */
public int signum() {
if( bitLength < 64) {
return Long.signum( this.smallValue );
@@ -1803,8 +1761,8 @@
/**
* Returns the scale of this {@code BigDecimal}. The scale is the number of
* digits behind the decimal point. The value of this {@code BigDecimal} is
- * the unsignedValue * 10^(-scale). If the scale is negative, then this
- * {@code BigDecimal} represents a big integer.
+ * the {@code unsignedValue * 10<sup>-scale</sup>}. If the scale is negative,
+ * then this {@code BigDecimal} represents a big integer.
*
* @return the scale of this {@code BigDecimal}.
*/
@@ -1852,10 +1810,8 @@
/**
* Returns the unscaled value (mantissa) of this {@code BigDecimal} instance
- * as a {@code BigInteger}. The unscaled value can be computed as {@code
- * this} 10^(scale).
- *
- * @return unscaled value (this * 10^(scale)).
+ * as a {@code BigInteger}. The unscaled value can be computed as
+ * {@code this * 10<sup>scale</sup>}.
*/
public BigInteger unscaledValue() {
return getUnscaledValue();
@@ -1983,17 +1939,13 @@
* Returns a new {@code BigDecimal} instance where the decimal point has
* been moved {@code n} places to the left. If {@code n < 0} then the
* decimal point is moved {@code -n} places to the right.
- * <p>
- * The result is obtained by changing its scale. If the scale of the result
+ *
+ * <p>The result is obtained by changing its scale. If the scale of the result
* becomes negative, then its precision is increased such that the scale is
* zero.
- * <p>
- * Note, that {@code movePointLeft(0)} returns a result which is
- * mathematically equivalent, but which has {@code scale >= 0}.
*
- * @param n
- * number of placed the decimal point has to be moved.
- * @return {@code this * 10^(-n}).
+ * <p>Note, that {@code movePointLeft(0)} returns a result which is
+ * mathematically equivalent, but which has {@code scale >= 0}.
*/
public BigDecimal movePointLeft(int n) {
return movePoint(scale + (long)n);
@@ -2025,33 +1977,25 @@
* Returns a new {@code BigDecimal} instance where the decimal point has
* been moved {@code n} places to the right. If {@code n < 0} then the
* decimal point is moved {@code -n} places to the left.
- * <p>
- * The result is obtained by changing its scale. If the scale of the result
+ *
+ * <p>The result is obtained by changing its scale. If the scale of the result
* becomes negative, then its precision is increased such that the scale is
* zero.
- * <p>
- * Note, that {@code movePointRight(0)} returns a result which is
- * mathematically equivalent, but which has scale >= 0.
*
- * @param n
- * number of placed the decimal point has to be moved.
- * @return {@code this * 10^n}.
+ * <p>Note, that {@code movePointRight(0)} returns a result which is
+ * mathematically equivalent, but which has scale >= 0.
*/
public BigDecimal movePointRight(int n) {
return movePoint(scale - (long)n);
}
/**
- * Returns a new {@code BigDecimal} whose value is {@code this} 10^{@code n}.
+ * Returns a new {@code BigDecimal} whose value is {@code this * 10<sup>n</sup>}.
* The scale of the result is {@code this.scale()} - {@code n}.
* The precision of the result is the precision of {@code this}.
- * <p>
- * This method has the same effect as {@link #movePointRight}, except that
- * the precision is not changed.
*
- * @param n
- * number of places the decimal point has to be moved.
- * @return {@code this * 10^n}
+ * <p>This method has the same effect as {@link #movePointRight}, except that
+ * the precision is not changed.
*/
public BigDecimal scaleByPowerOfTen(int n) {
long newScale = scale - (long)n;
@@ -2164,12 +2108,8 @@
* Returns {@code true} if {@code x} is a {@code BigDecimal} instance and if
* this instance is equal to this big decimal. Two big decimals are equal if
* their unscaled value and their scale is equal. For example, 1.0
- * (10*10^(-1)) is not equal to 1.00 (100*10^(-2)). Similarly, zero
+ * (10*10<sup>-1</sup>) is not equal to 1.00 (100*10<sup>-2</sup>). Similarly, zero
* instances are not equal if their scale differs.
- *
- * @param x
- * object to be compared with {@code this}.
- * @return true if {@code x} is a {@code BigDecimal} and {@code this == x}.
*/
@Override
public boolean equals(Object x) {
@@ -2181,8 +2121,6 @@
return x1.scale == scale
&& (bitLength < 64 ? (x1.smallValue == smallValue)
: intVal.equals(x1.intVal));
-
-
}
return false;
}
@@ -2455,9 +2393,7 @@
/**
* Returns this {@code BigDecimal} as an long value. Any fractional part is
* discarded. If the integral part of {@code this} is too big to be
- * represented as an long, then {@code this} % 2^64 is returned.
- *
- * @return this {@code BigDecimal} as a long value.
+ * represented as an long, then {@code this % 2<sup>64</sup>} is returned.
*/
@Override
public long longValue() {
@@ -2466,16 +2402,14 @@
* 10^(-scale). If the scale is positive and very large the long value
* could be zero.
*/
- return ((scale <= -64) || (scale > approxPrecision()) ? 0L
- : toBigInteger().longValue());
+ return ((scale <= -64) || (scale > approxPrecision()) ? 0L : toBigInteger().longValue());
}
/**
* Returns this {@code BigDecimal} as a long value if it has no fractional
- * part and if its value fits to the int range ([-2^{63}..2^{63}-1]). If
+ * part and if its value fits to the int range ([-2<sup>63</sup>..2<sup>63</sup>-1]). If
* these conditions are not met, an {@code ArithmeticException} is thrown.
*
- * @return this {@code BigDecimal} as a long value.
* @throws ArithmeticException
* if rounding is necessary or the number doesn't fit in a long.
*/
@@ -2486,9 +2420,7 @@
/**
* Returns this {@code BigDecimal} as an int value. Any fractional part is
* discarded. If the integral part of {@code this} is too big to be
- * represented as an int, then {@code this} % 2^32 is returned.
- *
- * @return this {@code BigDecimal} as a int value.
+ * represented as an int, then {@code this % 2<sup>32</sup>} is returned.
*/
@Override
public int intValue() {
@@ -2497,36 +2429,31 @@
* 10^(-scale). If the scale is positive and very large the long value
* could be zero.
*/
- return ((scale <= -32) || (scale > approxPrecision())
- ? 0
- : toBigInteger().intValue());
+ return ((scale <= -32) || (scale > approxPrecision()) ? 0 : toBigInteger().intValue());
}
/**
* Returns this {@code BigDecimal} as a int value if it has no fractional
- * part and if its value fits to the int range ([-2^{31}..2^{31}-1]). If
+ * part and if its value fits to the int range ([-2<sup>31</sup>..2<sup>31</sup>-1]). If
* these conditions are not met, an {@code ArithmeticException} is thrown.
*
- * @return this {@code BigDecimal} as a int value.
* @throws ArithmeticException
- * if rounding is necessary or the number doesn't fit in a int.
+ * if rounding is necessary or the number doesn't fit in an int.
*/
public int intValueExact() {
- return (int)valueExact(32);
+ return (int) valueExact(32);
}
/**
* Returns this {@code BigDecimal} as a short value if it has no fractional
- * part and if its value fits to the short range ([-2^{15}..2^{15}-1]). If
+ * part and if its value fits to the short range ([-2<sup>15</sup>..2<sup>15</sup>-1]). If
* these conditions are not met, an {@code ArithmeticException} is thrown.
*
- * @return this {@code BigDecimal} as a short value.
* @throws ArithmeticException
- * if rounding is necessary of the number doesn't fit in a
- * short.
+ * if rounding is necessary of the number doesn't fit in a short.
*/
public short shortValueExact() {
- return (short)valueExact(16);
+ return (short) valueExact(16);
}
/**
@@ -2534,12 +2461,11 @@
* part and if its value fits to the byte range ([-128..127]). If these
* conditions are not met, an {@code ArithmeticException} is thrown.
*
- * @return this {@code BigDecimal} as a byte value.
* @throws ArithmeticException
* if rounding is necessary or the number doesn't fit in a byte.
*/
public byte byteValueExact() {
- return (byte)valueExact(8);
+ return (byte) valueExact(8);
}
/**
@@ -2553,7 +2479,7 @@
* <p>
* For example, if the instance {@code x1 = new BigDecimal("0.1")} cannot be
* represented exactly as a float, and thus {@code x1.equals(new
- * BigDecimal(x1.folatValue())} returns {@code false} for this case.
+ * BigDecimal(x1.floatValue())} returns {@code false} for this case.
* <p>
* Similarly, if the instance {@code new BigDecimal(16777217)} is converted
* to a float, the result is {@code 1.6777216E}7.
@@ -2702,13 +2628,12 @@
* Returns the unit in the last place (ULP) of this {@code BigDecimal}
* instance. An ULP is the distance to the nearest big decimal with the same
* precision.
- * <p>
- * The amount of a rounding error in the evaluation of a floating-point
+ *
+ * <p>The amount of a rounding error in the evaluation of a floating-point
* operation is often expressed in ULPs. An error of 1 ULP is often seen as
* a tolerable error.
- * <p>
- * For class {@code BigDecimal}, the ULP of a number is simply 10^(-scale).
- * <p>
+ *
+ * <p>For class {@code BigDecimal}, the ULP of a number is simply 10<sup>-scale</sup>.
* For example, {@code new BigDecimal(0.1).ulp()} returns {@code 1E-55}.
*
* @return unit in the last place (ULP) of this {@code BigDecimal} instance.
diff --git a/luni/src/main/java/java/math/BigInteger.java b/luni/src/main/java/java/math/BigInteger.java
index e58bfd5..90bf0f6 100644
--- a/luni/src/main/java/java/math/BigInteger.java
+++ b/luni/src/main/java/java/math/BigInteger.java
@@ -24,7 +24,7 @@
import java.util.Random;
/**
- * An immutable signed integer of arbitrary magnitude.
+ * An immutable arbitrary-precision signed integer.
*
* <h3>Fast Cryptography</h3>
* This implementation is efficient for operations traditionally used in