You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/22 14:54:04 UTC
svn commit: r767497 [1/2] -
/harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/
Author: tellison
Date: Wed Apr 22 12:54:03 2009
New Revision: 767497
URL: http://svn.apache.org/viewvc?rev=767497&view=rev
Log:
Apply slightly modified patch for HARMONY-6161 (Javadocs for java.math.*)
The modifications were further comment tidy-up, including removing author tags and some useless comments (e.g. "constructors").
No functional changes.
Modified:
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigInteger.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BitLevel.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Conversion.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Division.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Elementary.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Logical.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/MathContext.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Multiplication.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/Primality.java
harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/RoundingMode.java
Modified: harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java?rev=767497&r1=767496&r2=767497&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/math/src/main/java/java/math/BigDecimal.java Wed Apr 22 12:54:03 2009
@@ -25,48 +25,95 @@
import org.apache.harmony.math.internal.nls.Messages;
/**
- * @author Intel Middleware Product Division
- * @author Instituto Tecnologico de Cordoba
+ * This class represents immutable arbitrary precision decimal numbers. Each
+ * {@code BigDecimal} instance is represented with a unscaled arbitrary
+ * precision mantissa (the unscaled value) and a scale. The value of the {@code
+ * BigDecimal} is {@code unscaledValue} 10^(-{@code scale}).
*/
public class BigDecimal extends Number implements Comparable<BigDecimal>, Serializable {
- /* Static Fields */
- /** @ar.org.fitc.spec_ref */
+ /**
+ * The constant zero as a {@code BigDecimal}.
+ */
public static final BigDecimal ZERO = new BigDecimal(0, 0);
- /** @ar.org.fitc.spec_ref */
+ /**
+ * The constant one as a {@code BigDecimal}.
+ */
public static final BigDecimal ONE = new BigDecimal(1, 0);
- /** @ar.org.fitc.spec_ref */
+ /**
+ * The constant ten as a {@code BigDecimal}.
+ */
public static final BigDecimal TEN = new BigDecimal(10, 0);
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode where positive values are rounded towards positive infinity
+ * and negative values towards negative infinity.
+ *
+ * @see RoundingMode#UP
+ */
public static final int ROUND_UP = 0;
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode where the values are rounded towards zero.
+ *
+ * @see RoundingMode#DOWN
+ */
public static final int ROUND_DOWN = 1;
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode to round towards positive infinity. For positive values
+ * this rounding mode behaves as {@link #ROUND_UP}, for negative values as
+ * {@link #ROUND_DOWN}.
+ *
+ * @see RoundingMode#CEILING
+ */
public static final int ROUND_CEILING = 2;
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode to round towards negative infinity. For positive values
+ * this rounding mode behaves as {@link #ROUND_DOWN}, for negative values as
+ * {@link #ROUND_UP}.
+ *
+ * @see RoundingMode#FLOOR
+ */
public static final int ROUND_FLOOR = 3;
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode where values are rounded towards the nearest neighbor.
+ * Ties are broken by rounding up.
+ *
+ * @see RoundingMode#HALF_UP
+ */
public static final int ROUND_HALF_UP = 4;
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode where values are rounded towards the nearest neighbor.
+ * Ties are broken by rounding down.
+ *
+ * @see RoundingMode#HALF_DOWN
+ */
public static final int ROUND_HALF_DOWN = 5;
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode where values are rounded towards the nearest neighbor.
+ * Ties are broken by rounding to the even neighbor.
+ *
+ * @see RoundingMode#HALF_EVEN
+ */
public static final int ROUND_HALF_EVEN = 6;
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Rounding mode where the rounding operations throws an {@code
+ * ArithmeticException} for the case that rounding is necessary, i.e. for
+ * the case that the value cannot be represented exactly.
+ *
+ * @see RoundingMode#UNNECESSARY
+ */
public static final int ROUND_UNNECESSARY = 7;
- /* Private Fields */
-
- /** @ar.org.fitc.spec_ref */
+ /** This is the serialVersionUID used by the sun implementation. */
private static final long serialVersionUID = 6108874887143696463L;
/** The double closer to <code>Log10(2)</code>. */
@@ -74,24 +121,25 @@
/** The <code>String</code> representation is cached. */
private transient String toStringImage = null;
-
+
+ /** Cache for the hash code. */
private transient int hashCode = 0;
/**
* An array with powers of five that fit in the type <code>long</code>
- * (<code>5^0,5^1,...,5^27</code>)
+ * (<code>5^0,5^1,...,5^27</code>).
*/
private static final BigInteger FIVE_POW[];
/**
* An array with powers of ten that fit in the type <code>long</code>
- * (<code>10^0,10^1,...,10^18</code>)
+ * (<code>10^0,10^1,...,10^18</code>).
*/
private static final BigInteger TEN_POW[];
/**
* An array with powers of ten that fit in the type <code>long</code>
- * (<code>10^0,10^1,...,10^18</code>)
+ * (<code>10^0,10^1,...,10^18</code>).
*/
private static final long[] LONG_TEN_POW = new long[]
{ 1L,
@@ -149,15 +197,16 @@
private static final int[] LONG_TEN_POW_BIT_LENGTH = new int[LONG_TEN_POW.length];
private static final int BI_SCALED_BY_ZERO_LENGTH = 11;
+
/**
* An array with the first <code>BigInteger</code> scaled by zero.
- * (<code>[0,0],[1,0],...,[10,0]</code>)
+ * (<code>[0,0],[1,0],...,[10,0]</code>).
*/
private static final BigDecimal BI_SCALED_BY_ZERO[] = new BigDecimal[BI_SCALED_BY_ZERO_LENGTH];
/**
* An array with the zero number scaled by the first positive scales.
- * (<code>0*10^0, 0*10^1, ..., 0*10^10</code>)
+ * (<code>0*10^0, 0*10^1, ..., 0*10^10</code>).
*/
private static final BigDecimal ZERO_SCALED_BY[] = new BigDecimal[11];
@@ -191,7 +240,7 @@
/**
* The arbitrary precision integer (unscaled value) in the internal
- * representation of <code>BigDecimal</code>.
+ * representation of {@code BigDecimal}.
*/
private BigInteger intVal;
@@ -200,22 +249,21 @@
private transient long smallValue;
/**
- * The 32-bit integer scale in the internal representation of <code>BigDecimal</code>.
+ * The 32-bit integer scale in the internal representation of {@code BigDecimal}.
*/
private int scale;
/**
- * Represent the number of decimal digits in the unscaled value. This
- * precision is calculated the first time, and used in the following
- * calls of method <code>precision()</code>. Note that some call to
- * the private method <code>inplaceRound()</code> could update this field.
+ * Represent the number of decimal digits in the unscaled value. This
+ * precision is calculated the first time, and used in the following calls
+ * of method <code>precision()</code>. Note that some call to the private
+ * method <code>inplaceRound()</code> could update this field.
+ *
* @see #precision()
* @see #inplaceRound(MathContext)
*/
private transient int precision = 0;
- /* Constructors */
-
private BigDecimal(long smallValue, int scale){
this.smallValue = smallValue;
this.scale = scale;
@@ -227,9 +275,27 @@
this.scale = scale;
this.bitLength = bitLength(smallValue);
}
-
-
- /** @ar.org.fitc.spec_ref */
+
+ /**
+ * Constructs a new {@code BigDecimal} instance from a string representation
+ * given as a character array.
+ *
+ * @param in
+ * array of characters containing the string representation of
+ * this {@code BigDecimal}.
+ * @param offset
+ * first index to be copied.
+ * @param len
+ * number of characters to be used.
+ * @throws NullPointerException
+ * if {@code in == null}.
+ * @throws NumberFormatException
+ * if {@code offset < 0} or {@code len <= 0} or {@code
+ * offset+len-1 < 0} or {@code offset+len-1 >= in.length}.
+ * @throws NumberFormatException
+ * if in does not contain a valid string representation of a big
+ * decimal.
+ */
public BigDecimal(char[] in, int offset, int len) {
int begin = offset; // first index to be copied
int last = offset + (len - 1); // last index to be copied
@@ -256,12 +322,12 @@
for (; (offset <= last) && (in[offset] != '.')
&& (in[offset] != 'e') && (in[offset] != 'E'); offset++) {
if (!wasNonZero) {
- if (in[offset] == '0') {
- counter++;
- } else {
- wasNonZero = true;
- }
- };
+ if (in[offset] == '0') {
+ counter++;
+ } else {
+ wasNonZero = true;
+ }
+ }
}
unscaledBuffer.append(in, begin, offset - begin);
@@ -273,13 +339,13 @@
begin = offset;
for (; (offset <= last) && (in[offset] != 'e')
&& (in[offset] != 'E'); offset++) {
- if (!wasNonZero) {
- if (in[offset] == '0') {
- counter++;
- } else {
- wasNonZero = true;
- }
- };
+ if (!wasNonZero) {
+ if (in[offset] == '0') {
+ counter++;
+ } else {
+ wasNonZero = true;
+ }
+ }
}
scale = offset - begin;
bufLength +=scale;
@@ -310,8 +376,8 @@
}
// Parsing the unscaled value
if (bufLength < 19) {
- smallValue = Long.parseLong(unscaledBuffer.toString());
- bitLength = bitLength(smallValue);
+ smallValue = Long.parseLong(unscaledBuffer.toString());
+ bitLength = bitLength(smallValue);
} else {
setUnscaledValue(new BigInteger(unscaledBuffer.toString()));
}
@@ -321,35 +387,132 @@
}
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from a string representation
+ * given as a character array.
+ *
+ * @param in
+ * array of characters containing the string representation of
+ * this {@code BigDecimal}.
+ * @param offset
+ * first index to be copied.
+ * @param len
+ * number of characters to be used.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @throws NullPointerException
+ * if {@code in == null}.
+ * @throws NumberFormatException
+ * if {@code offset < 0} or {@code len <= 0} or {@code
+ * offset+len-1 < 0} or {@code offset+len-1 >= in.length}.
+ * @throws NumberFormatException
+ * if {@code in} does not contain a valid string representation
+ * of a big decimal.
+ * @throws ArithmeticException
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ */
public BigDecimal(char[] in, int offset, int len, MathContext mc) {
this(in, offset, len);
inplaceRound(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from a string representation
+ * given as a character array.
+ *
+ * @param in
+ * array of characters containing the string representation of
+ * this {@code BigDecimal}.
+ * @throws NullPointerException
+ * if {@code in == null}.
+ * @throws NumberFormatException
+ * if {@code in} does not contain a valid string representation
+ * of a big decimal.
+ */
public BigDecimal(char[] in) {
this(in, 0, in.length);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from a string representation
+ * given as a character array. The result is rounded according to the
+ * specified math context.
+ *
+ * @param in
+ * array of characters containing the string representation of
+ * this {@code BigDecimal}.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @throws NullPointerException
+ * if {@code in == null}.
+ * @throws NumberFormatException
+ * if {@code in} does not contain a valid string representation
+ * of a big decimal.
+ * @throws ArithmeticException
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ */
public BigDecimal(char[] in, MathContext mc) {
this(in, 0, in.length);
inplaceRound(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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.
+ */
public BigDecimal(String val) {
this(val.toCharArray(), 0, val.length());
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from a string
+ * 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
+ * if {@code val} does not contain a valid string representation
+ * of a big decimal.
+ * @throws ArithmeticException
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ */
public BigDecimal(String val, MathContext mc) {
this(val.toCharArray(), 0, val.length());
inplaceRound(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from the 64bit double
+ * {@code val}. The constructed big decimal is equivalent to the given
+ * double. For example, {@code new BigDecimal(0.1)} is equal to {@code
+ * 0.1000000000000000055511151231257827021181583404541015625}. This happens
+ * as {@code 0.1} cannot be represented exactly in binary.
+ * <p>
+ * To generate a big decimal instance which is equivalent to {@code 0.1} use
+ * the {@code BigDecimal(String)} constructor.
+ *
+ * @param val
+ * double value to be converted to a {@code BigDecimal} instance.
+ * @throws NumberFormatException
+ * if {@code val} is infinity or not a number.
+ */
public BigDecimal(double val) {
if (Double.isInfinite(val) || Double.isNaN(val)) {
// math.03=Infinity or NaN
@@ -401,24 +564,76 @@
}
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from the 64bit double
+ * {@code val}. The constructed big decimal is equivalent to the given
+ * double. For example, {@code new BigDecimal(0.1)} is equal to {@code
+ * 0.1000000000000000055511151231257827021181583404541015625}. This happens
+ * as {@code 0.1} cannot be represented exactly in binary.
+ * <p>
+ * To generate a big decimal instance which is equivalent to {@code 0.1} use
+ * the {@code BigDecimal(String)} constructor.
+ *
+ * @param val
+ * double value to be converted to a {@code BigDecimal} instance.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @throws NumberFormatException
+ * if {@code val} is infinity or not a number.
+ * @throws ArithmeticException
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ */
public BigDecimal(double val, MathContext mc) {
this(val);
inplaceRound(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ */
public BigDecimal(BigInteger val, MathContext mc) {
this(val);
inplaceRound(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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}).
+ *
+ * @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}.
+ */
public BigDecimal(BigInteger unscaledVal, int scale) {
if (unscaledVal == null) {
throw new NullPointerException();
@@ -427,29 +642,86 @@
setUnscaledValue(unscaledVal);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ * @throws NullPointerException
+ * if {@code unscaledVal == null}.
+ */
public BigDecimal(BigInteger unscaledVal, int scale, MathContext mc) {
this(unscaledVal, scale);
inplaceRound(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from the given int
+ * {@code val}. The scale of the result is 0.
+ *
+ * @param val
+ * int value to be converted to a {@code BigDecimal} instance.
+ */
public BigDecimal(int val) {
this(val,0);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from the given int {@code
+ * val}. The scale of the result is {@code 0}. The result is rounded
+ * according to the specified math context.
+ *
+ * @param val
+ * int value to be converted to a {@code BigDecimal} instance.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @throws ArithmeticException
+ * if {@code mc.precision > 0} and {@code c.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ */
public BigDecimal(int val, MathContext mc) {
this(val,0);
inplaceRound(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from the given long {@code
+ * val}. The scale of the result is {@code 0}.
+ *
+ * @param val
+ * long value to be converted to a {@code BigDecimal} instance.
+ */
public BigDecimal(long val) {
this(val,0);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Constructs a new {@code BigDecimal} instance from the given long {@code
+ * val}. The scale of the result is {@code 0}. The result is rounded
+ * according to the specified math context.
+ *
+ * @param val
+ * long value to be converted to a {@code BigDecimal} instance.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @throws ArithmeticException
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and the new big decimal cannot be represented
+ * within the given precision without rounding.
+ */
public BigDecimal(long val, MathContext mc) {
this(val);
inplaceRound(mc);
@@ -457,7 +729,19 @@
/* Public Methods */
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} instance whose value is equal to {@code
+ * unscaledVal} 10^(-{@code scale}). 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) {
return valueOf(unscaledVal);
@@ -469,7 +753,15 @@
return new BigDecimal(unscaledVal, scale);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} instance whose value is equal to {@code
+ * unscaledVal}. The scale of the result is {@code 0}, and its unscaled
+ * value is {@code unscaledVal}.
+ *
+ * @param unscaledVal
+ * value to be converted to a {@code BigDecimal}.
+ * @return {@code BigDecimal} instance with the value {@code unscaledVal}.
+ */
public static BigDecimal valueOf(long unscaledVal) {
if ((unscaledVal >= 0) && (unscaledVal < BI_SCALED_BY_ZERO_LENGTH)) {
return BI_SCALED_BY_ZERO[(int)unscaledVal];
@@ -477,7 +769,24 @@
return new BigDecimal(unscaledVal,0);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} instance whose value is equal to {@code
+ * val}. The new decimal is constructed as if the {@code BigDecimal(String)}
+ * constructor is called with an argument which is equal to {@code
+ * Double.toString(val)}. For example, {@code valueOf("0.1")} is converted to
+ * (unscaled=1, scale=1), although the double {@code 0.1} cannot be
+ * represented exactly as a double value. In contrast to that, a new {@code
+ * BigDecimal(0.1)} instance has the value {@code
+ * 0.1000000000000000055511151231257827021181583404541015625} with an
+ * unscaled value {@code 1000000000000000055511151231257827021181583404541015625}
+ * and the scale {@code 55}.
+ *
+ * @param val
+ * double value to be converted to a {@code BigDecimal}.
+ * @return {@code BigDecimal} instance with the value {@code val}.
+ * @throws NumberFormatException
+ * if {@code val} is infinite or {@code val} is not a number
+ */
public static BigDecimal valueOf(double val) {
if (Double.isInfinite(val) || Double.isNaN(val)) {
// math.03=Infinity or NaN
@@ -486,7 +795,17 @@
return new BigDecimal(Double.toString(val));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this + augend}.
+ * The scale of the result is the maximum of the scales of the two
+ * arguments.
+ *
+ * @param augend
+ * value to be added to {@code this}.
+ * @return {@code this + augend}.
+ * @throws NullPointerException
+ * if {@code augend == null}.
+ */
public BigDecimal add(BigDecimal augend) {
int diffScale = this.scale - augend.scale;
// Fast return when some operand is zero
@@ -526,7 +845,18 @@
Multiplication.multiplyByTenPow(augend.getUnscaledValue(),diffScale)), thisValue.scale);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this + augend}.
+ * The result is rounded according to the passed context {@code mc}.
+ *
+ * @param augend
+ * value to be added to {@code this}.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code this + augend}.
+ * @throws NullPointerException
+ * if {@code augend == null} or {@code mc == null}.
+ */
public BigDecimal add(BigDecimal augend, MathContext mc) {
BigDecimal larger; // operand with the largest unscaled value
BigDecimal smaller; // operand with the smallest unscaled value
@@ -568,7 +898,16 @@
return larger.round(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this - subtrahend}.
+ * The scale of the result is the maximum of the scales of the two arguments.
+ *
+ * @param subtrahend
+ * value to be subtracted from {@code this}.
+ * @return {@code this - subtrahend}.
+ * @throws NullPointerException
+ * if {@code subtrahend == null}.
+ */
public BigDecimal subtract(BigDecimal subtrahend) {
int diffScale = this.scale - subtrahend.scale;
// Fast return when some operand is zero
@@ -610,7 +949,18 @@
}
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this - subtrahend}.
+ * The result is rounded according to the passed context {@code mc}.
+ *
+ * @param subtrahend
+ * value to be subtracted from {@code this}.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code this - subtrahend}.
+ * @throws NullPointerException
+ * if {@code subtrahend == null} or {@code mc == null}.
+ */
public BigDecimal subtract(BigDecimal subtrahend, MathContext mc) {
long diffScale = subtrahend.scale - (long)this.scale;
int thisSignum;
@@ -643,7 +993,17 @@
return subtract(subtrahend).round(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this *
+ * multiplicand}. The scale of the result is the sum of the scales of the
+ * two arguments.
+ *
+ * @param multiplicand
+ * value to be multiplied with {@code this}.
+ * @return {@code this * multiplicand}.
+ * @throws NullPointerException
+ * if {@code multiplicand == null}.
+ */
public BigDecimal multiply(BigDecimal multiplicand) {
long newScale = (long)this.scale + multiplicand.scale;
@@ -659,7 +1019,19 @@
multiplicand.getUnscaledValue()), toIntScale(newScale));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this *
+ * multiplicand}. The result is rounded according to the passed context
+ * {@code mc}.
+ *
+ * @param multiplicand
+ * value to be multiplied with {@code this}.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code this * multiplicand}.
+ * @throws NullPointerException
+ * if {@code multiplicand == null} or {@code mc == null}.
+ */
public BigDecimal multiply(BigDecimal multiplicand, MathContext mc) {
BigDecimal result = multiply(multiplicand);
@@ -667,12 +1039,57 @@
return result;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+ * As scale of the result the parameter {@code scale} is used. If rounding
+ * is required to meet the specified scale, then the specified rounding mode
+ * {@code roundingMode} is applied.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param scale
+ * the scale of the result returned.
+ * @param roundingMode
+ * rounding mode to be used to round the result.
+ * @return {@code this / divisor} rounded according to the given rounding
+ * mode.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws IllegalArgumentException
+ * if {@code roundingMode} is not a valid rounding mode.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+ * necessary according to the given scale.
+ */
public BigDecimal divide(BigDecimal divisor, int scale, int roundingMode) {
return divide(divisor, scale, RoundingMode.valueOf(roundingMode));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+ * As scale of the result the parameter {@code scale} is used. If rounding
+ * is required to meet the specified scale, then the specified rounding mode
+ * {@code roundingMode} is applied.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param scale
+ * the scale of the result returned.
+ * @param roundingMode
+ * rounding mode to be used to round the result.
+ * @return {@code this / divisor} rounded according to the given rounding
+ * mode.
+ * @throws NullPointerException
+ * if {@code divisor == null} or {@code roundingMode == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if {@code roundingMode == RoundingMode.UNNECESSAR}Y and
+ * rounding is necessary according to the given scale and given
+ * precision.
+ */
public BigDecimal divide(BigDecimal divisor, int scale, RoundingMode roundingMode) {
// Let be: this = [u1,s1] and divisor = [u2,s2]
if (roundingMode == null) {
@@ -775,17 +1192,73 @@
return valueOf(quotient, scale);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+ * The scale of the result is the scale of {@code this}. If rounding is
+ * required to meet the specified scale, then the specified rounding mode
+ * {@code roundingMode} is applied.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param roundingMode
+ * rounding mode to be used to round the result.
+ * @return {@code this / divisor} rounded according to the given rounding
+ * mode.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws IllegalArgumentException
+ * if {@code roundingMode} is not a valid rounding mode.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+ * necessary according to the scale of this.
+ */
public BigDecimal divide(BigDecimal divisor, int roundingMode) {
return divide(divisor, scale, RoundingMode.valueOf(roundingMode));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+ * The scale of the result is the scale of {@code this}. If rounding is
+ * required to meet the specified scale, then the specified rounding mode
+ * {@code roundingMode} is applied.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param roundingMode
+ * rounding mode to be used to round the result.
+ * @return {@code this / divisor} rounded according to the given rounding
+ * mode.
+ * @throws NullPointerException
+ * if {@code divisor == null} or {@code roundingMode == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if {@code roundingMode == RoundingMode.UNNECESSARY} and
+ * rounding is necessary according to the scale of this.
+ */
public BigDecimal divide(BigDecimal divisor, RoundingMode roundingMode) {
return divide(divisor, scale, roundingMode);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+ * The scale of the result is the difference of the scales of {@code this}
+ * and {@code divisor}. If the exact result requires more digits, then the
+ * scale is adjusted accordingly. For example, {@code 1/128 = 0.0078125}
+ * which has a scale of {@code 7} and precision {@code 5}.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @return {@code this / divisor}.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if the result cannot be represented exactly.
+ */
public BigDecimal divide(BigDecimal divisor) {
BigInteger p = this.getUnscaledValue();
BigInteger q = divisor.getUnscaledValue();
@@ -847,7 +1320,25 @@
return new BigDecimal(p, newScale);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this / divisor}.
+ * The result is rounded according to the passed context {@code mc}. If the
+ * passed math context specifies precision {@code 0}, then this call is
+ * equivalent to {@code this.divide(divisor)}.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code this / divisor}.
+ * @throws NullPointerException
+ * if {@code divisor == null} or {@code mc == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if {@code mc.getRoundingMode() == UNNECESSARY} and rounding
+ * is necessary according {@code mc.getPrecision()}.
+ */
public BigDecimal divide(BigDecimal divisor, MathContext mc) {
/* Calculating how many zeros must be append to 'dividend'
* to obtain a quotient with at least 'mc.precision()' digits */
@@ -903,7 +1394,19 @@
return new BigDecimal(integerQuot, toIntScale(newScale), mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is the integral part of
+ * {@code this / divisor}. The quotient is rounded down towards zero to the
+ * next integer. For example, {@code 0.5/0.2 = 2}.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @return integral part of {@code this / divisor}.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ */
public BigDecimal divideToIntegralValue(BigDecimal divisor) {
BigInteger integralValue; // the integer of result
BigInteger powerOfTen; // some power of ten
@@ -955,7 +1458,27 @@
: new BigDecimal(integralValue, toIntScale(newScale)));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is the integral part of
+ * {@code this / divisor}. The quotient is rounded down towards zero to the
+ * next integer. The rounding mode passed with the parameter {@code mc} is
+ * not considered. But if the precision of {@code mc > 0} and the integral
+ * part requires more digits, then an {@code ArithmeticException} is thrown.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param mc
+ * math context which determines the maximal precision of the
+ * result.
+ * @return integral part of {@code this / divisor}.
+ * @throws NullPointerException
+ * if {@code divisor == null} or {@code mc == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if {@code mc.getPrecision() > 0} and the result requires more
+ * digits to be represented.
+ */
public BigDecimal divideToIntegralValue(BigDecimal divisor, MathContext mc) {
int mcPrecision = mc.getPrecision();
int diffPrecision = this.precision() - divisor.precision();
@@ -1047,17 +1570,67 @@
return integralValue;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this % divisor}.
+ * <p>
+ * The remainder is defined as {@code this -
+ * this.divideToIntegralValue(divisor) * divisor}.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @return {@code this % divisor}.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ */
public BigDecimal remainder(BigDecimal divisor) {
return divideAndRemainder(divisor)[1];
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this % divisor}.
+ * <p>
+ * The remainder is defined as {@code this -
+ * this.divideToIntegralValue(divisor) * divisor}.
+ * <p>
+ * The specified rounding mode {@code mc} is used for the division only.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param mc
+ * rounding mode and precision to be used.
+ * @return {@code this % divisor}.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @throws ArithmeticException
+ * if {@code mc.getPrecision() > 0} and the result of {@code
+ * this.divideToIntegralValue(divisor, mc)} requires more digits
+ * to be represented.
+ */
public BigDecimal remainder(BigDecimal divisor, MathContext mc) {
return divideAndRemainder(divisor, mc)[1];
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a {@code BigDecimal} array which contains the integral part of
+ * {@code this / divisor} at index 0 and the remainder {@code this %
+ * divisor} at index 1. The quotient is rounded down towards zero to the
+ * next integer.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @return {@code [this.divideToIntegralValue(divisor),
+ * this.remainder(divisor)]}.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @see #divideToIntegralValue
+ * @see #remainder
+ */
public BigDecimal[] divideAndRemainder(BigDecimal divisor) {
BigDecimal quotAndRem[] = new BigDecimal[2];
@@ -1066,7 +1639,28 @@
return quotAndRem;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a {@code BigDecimal} array which contains the integral part of
+ * {@code this / divisor} at index 0 and the remainder {@code this %
+ * divisor} at index 1. The quotient is rounded down towards zero to the
+ * next integer. The rounding mode passed with the parameter {@code mc} is
+ * not considered. But if the precision of {@code mc > 0} and the integral
+ * part requires more digits, then an {@code ArithmeticException} is thrown.
+ *
+ * @param divisor
+ * value by which {@code this} is divided.
+ * @param mc
+ * math context which determines the maximal precision of the
+ * result.
+ * @return {@code [this.divideToIntegralValue(divisor),
+ * this.remainder(divisor)]}.
+ * @throws NullPointerException
+ * if {@code divisor == null}.
+ * @throws ArithmeticException
+ * if {@code divisor == 0}.
+ * @see #divideToIntegralValue
+ * @see #remainder
+ */
public BigDecimal[] divideAndRemainder(BigDecimal divisor, MathContext mc) {
BigDecimal quotAndRem[] = new BigDecimal[2];
@@ -1075,7 +1669,21 @@
return quotAndRem;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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}.
+ */
public BigDecimal pow(int n) {
if (n == 0) {
return ONE;
@@ -1091,7 +1699,21 @@
: new BigDecimal(getUnscaledValue().pow(n), toIntScale(newScale)));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this ^ n}. The
+ * result is rounded according to the passed context {@code mc}.
+ * <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}.
+ */
public BigDecimal pow(int n, MathContext mc) {
// The ANSI standard X3.274-1996 algorithm
int m = Math.abs(n);
@@ -1134,17 +1756,35 @@
return accum;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is the absolute value of
+ * {@code this}. The scale of the result is the same as the scale of this.
+ *
+ * @return {@code abs(this)}
+ */
public BigDecimal abs() {
return ((signum() < 0) ? negate() : this);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is the absolute value of
+ * {@code this}. The result is rounded according to the passed context
+ * {@code mc}.
+ *
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code abs(this)}
+ */
public BigDecimal abs(MathContext mc) {
return round(mc).abs();
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is the {@code -this}. The
+ * scale of the result is the same as the scale of this.
+ *
+ * @return {@code -this}
+ */
public BigDecimal negate() {
if(bitLength < 63 || (bitLength == 63 && smallValue!=Long.MIN_VALUE)) {
return valueOf(-smallValue,scale);
@@ -1152,22 +1792,46 @@
return new BigDecimal(getUnscaledValue().negate(), scale);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is the {@code -this}. The
+ * result is rounded according to the passed context {@code mc}.
+ *
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code -this}
+ */
public BigDecimal negate(MathContext mc) {
return round(mc).negate();
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code +this}. The scale
+ * of the result is the same as the scale of this.
+ *
+ * @return {@code this}
+ */
public BigDecimal plus() {
return this;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code +this}. The result
+ * is rounded according to the passed context {@code mc}.
+ *
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code this}, rounded
+ */
public BigDecimal plus(MathContext mc) {
return round(mc);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns the sign of this {@code BigDecimal}.
+ *
+ * @return {@code -1} if {@code this < 0},
+ * {@code 0} if {@code this == 0},
+ * {@code 1} if {@code this > 0}. */
public int signum() {
if( bitLength < 64) {
return Long.signum( this.smallValue );
@@ -1180,12 +1844,26 @@
return bitLength == 0 && this.smallValue != -1;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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.
+ *
+ * @return the scale of this {@code BigDecimal}.
+ */
public int scale() {
return scale;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns the precision of this {@code BigDecimal}. The precision is the
+ * number of decimal digits used to represent this decimal. It is equivalent
+ * to the number of digits of the unscaled value. The precision of {@code 0}
+ * is {@code 1} (independent of the scale).
+ *
+ * @return the precision of this {@code BigDecimal}.
+ */
public int precision() {
// Checking if the precision already was calculated
if (precision > 0) {
@@ -1216,12 +1894,35 @@
return precision;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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)).
+ */
public BigInteger unscaledValue() {
return getUnscaledValue();
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this}, rounded
+ * according to the passed context {@code mc}.
+ * <p>
+ * If {@code mc.precision = 0}, then no rounding is performed.
+ * <p>
+ * If {@code mc.precision > 0} and {@code mc.roundingMode == UNNECESSARY},
+ * then an {@code ArithmeticException} is thrown if the result cannot be
+ * represented exactly within the given precision.
+ *
+ * @param mc
+ * rounding mode and precision for the result of this operation.
+ * @return {@code this} rounded according to the passed context.
+ * @throws ArithmeticException
+ * if {@code mc.precision > 0} and {@code mc.roundingMode ==
+ * UNNECESSARY} and this cannot be represented within the given
+ * precision.
+ */
public BigDecimal round(MathContext mc) {
BigDecimal thisBD = new BigDecimal(getUnscaledValue(), scale);
@@ -1229,7 +1930,28 @@
return thisBD;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} instance with the specified scale.
+ * <p>
+ * If the new scale is greater than the old scale, then additional zeros are
+ * added to the unscaled value. In this case no rounding is necessary.
+ * <p>
+ * If the new scale is smaller than the old scale, then trailing digits are
+ * removed. If these trailing digits are not zero, then the remaining
+ * unscaled value has to be rounded. For this rounding operation the
+ * specified rounding mode is used.
+ *
+ * @param newScale
+ * scale of the result returned.
+ * @param roundingMode
+ * rounding mode to be used to round the result.
+ * @return a new {@code BigDecimal} instance with the specified scale.
+ * @throws NullPointerException
+ * if {@code roundingMode == null}.
+ * @throws ArithmeticException
+ * if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+ * necessary according to the given scale.
+ */
public BigDecimal setScale(int newScale, RoundingMode roundingMode) {
if (roundingMode == null) {
throw new NullPointerException();
@@ -1255,17 +1977,68 @@
return divideBigIntegers(this.getUnscaledValue(),Multiplication.powerOf10(-diffScale),newScale,roundingMode);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} instance with the specified scale.
+ * <p>
+ * If the new scale is greater than the old scale, then additional zeros are
+ * added to the unscaled value. In this case no rounding is necessary.
+ * <p>
+ * If the new scale is smaller than the old scale, then trailing digits are
+ * removed. If these trailing digits are not zero, then the remaining
+ * unscaled value has to be rounded. For this rounding operation the
+ * specified rounding mode is used.
+ *
+ * @param newScale
+ * scale of the result returned.
+ * @param roundingMode
+ * rounding mode to be used to round the result.
+ * @return a new {@code BigDecimal} instance with the specified scale.
+ * @throws IllegalArgumentException
+ * if {@code roundingMode} is not a valid rounding mode.
+ * @throws ArithmeticException
+ * if {@code roundingMode == ROUND_UNNECESSARY} and rounding is
+ * necessary according to the given scale.
+ */
public BigDecimal setScale(int newScale, int roundingMode) {
return setScale(newScale, RoundingMode.valueOf(roundingMode));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} instance with the specified scale. If
+ * the new scale is greater than the old scale, then additional zeros are
+ * added to the unscaled value. If the new scale is smaller than the old
+ * scale, then trailing zeros are removed. If the trailing digits are not
+ * zeros then an ArithmeticException is thrown.
+ * <p>
+ * If no exception is thrown, then the following equation holds: {@code
+ * x.setScale(s).compareTo(x) == 0}.
+ *
+ * @param newScale
+ * scale of the result returned.
+ * @return a new {@code BigDecimal} instance with the specified scale.
+ * @throws ArithmeticException
+ * if rounding would be necessary.
+ */
public BigDecimal setScale(int newScale) {
return setScale(newScale, RoundingMode.UNNECESSARY);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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}).
+ */
public BigDecimal movePointLeft(int n) {
return movePoint(scale + (long)n);
}
@@ -1289,12 +2062,38 @@
return new BigDecimal(Multiplication.multiplyByTenPow(getUnscaledValue(),(int)-newScale), 0);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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}.
+ */
public BigDecimal movePointRight(int n) {
return movePoint(scale - (long)n);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} whose value is {@code this} 10^{@code n}.
+ * 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}
+ */
public BigDecimal scaleByPowerOfTen(int n) {
long newScale = scale - (long)n;
if(bitLength < 64) {
@@ -1307,7 +2106,15 @@
return new BigDecimal(getUnscaledValue(), toIntScale(newScale));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a new {@code BigDecimal} instance with the same value as {@code
+ * this} but with a unscaled value where the trailing zeros have been
+ * removed. If the unscaled value of {@code this} has n trailing zeros, then
+ * the scale and the precision of the result has been reduced by n.
+ *
+ * @return a new {@code BigDecimal} instance equivalent to this where the
+ * trailing zeros of the unscaled value have been removed.
+ */
public BigDecimal stripTrailingZeros() {
int i = 1; // 1 <= i <= 18
int lastPow = TEN_POW.length - 1;
@@ -1344,7 +2151,22 @@
return new BigDecimal(strippedBI, toIntScale(newScale));
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Compares this {@code BigDecimal} with {@code val}. Returns one of the
+ * three values {@code 1}, {@code 0}, or {@code -1}. The method behaves as
+ * if {@code this.subtract(val)} is computed. If this difference is > 0 then
+ * 1 is returned, if the difference is < 0 then -1 is returned, and if the
+ * difference is 0 then 0 is returned. This means, that if two decimal
+ * instances are compared which are equal in value but differ in scale, then
+ * these two instances are considered as equal.
+ *
+ * @param val
+ * value to be compared with {@code this}.
+ * @return {@code 1} if {@code this > val}, {@code -1} if {@code this < val},
+ * {@code 0} if {@code this == val}.
+ * @throws NullPointerException
+ * if {@code val == null}.
+ */
public int compareTo(BigDecimal val) {
int thisSign = signum();
int valueSign = val.signum();
@@ -1377,50 +2199,90 @@
}
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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) {
- if (this == x) {
- return true;
- }
- if (x instanceof BigDecimal) {
- BigDecimal x1 = (BigDecimal) x;
- return x1.scale == scale
+ public boolean equals(Object x) {
+ if (this == x) {
+ return true;
+ }
+ if (x instanceof BigDecimal) {
+ BigDecimal x1 = (BigDecimal) x;
+ return x1.scale == scale
&& (bitLength < 64 ? (x1.smallValue == smallValue)
: intVal.equals(x1.intVal));
-
-
- }
- return false;
+
+
+ }
+ return false;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns the minimum of this {@code BigDecimal} and {@code val}.
+ *
+ * @param val
+ * value to be used to compute the minimum with this.
+ * @return {@code min(this, val}.
+ * @throws NullPointerException
+ * if {@code val == null}.
+ */
public BigDecimal min(BigDecimal val) {
return ((compareTo(val) <= 0) ? this : val);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns the maximum of this {@code BigDecimal} and {@code val}.
+ *
+ * @param val
+ * value to be used to compute the maximum with this.
+ * @return {@code max(this, val}.
+ * @throws NullPointerException
+ * if {@code val == null}.
+ */
public BigDecimal max(BigDecimal val) {
return ((compareTo(val) >= 0) ? this : val);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a hash code for this {@code BigDecimal}.
+ *
+ * @return hash code for {@code this}.
+ */
@Override
public int hashCode() {
- if (hashCode != 0) {
- return hashCode;
- }
- if (bitLength < 64) {
- hashCode = (int)(smallValue & 0xffffffff);
- hashCode = 33 * hashCode + (int)((smallValue >> 32) & 0xffffffff);
- hashCode = 17 * hashCode + scale;
- return hashCode;
- }
- hashCode = 17 * intVal.hashCode() + scale;
- return hashCode;
+ if (hashCode != 0) {
+ return hashCode;
+ }
+ if (bitLength < 64) {
+ hashCode = (int)(smallValue & 0xffffffff);
+ hashCode = 33 * hashCode + (int)((smallValue >> 32) & 0xffffffff);
+ hashCode = 17 * hashCode + scale;
+ return hashCode;
+ }
+ hashCode = 17 * intVal.hashCode() + scale;
+ return hashCode;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a canonical string representation of this {@code BigDecimal}. If
+ * necessary, scientific notation is used. This representation always prints
+ * all significant digits of this value.
+ * <p>
+ * If the scale is negative or if {@code scale - precision >= 6} then
+ * scientific notation is used.
+ *
+ * @return a string representation of {@code this} in scientific notation if
+ * necessary.
+ */
@Override
public String toString() {
if (toStringImage != null) {
@@ -1462,7 +2324,18 @@
return toStringImage;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a string representation of this {@code BigDecimal}. This
+ * representation always prints all significant digits of this value.
+ * <p>
+ * If the scale is negative or if {@code scale - precision >= 6} then
+ * engineering notation is used. Engineering notation is similar to the
+ * scientific notation except that the exponent is made to be a multiple of
+ * 3 such that the integer part is >= 1 and < 1000.
+ *
+ * @return a string representation of {@code this} in engineering notation
+ * if necessary.
+ */
public String toEngineeringString() {
String intString = getUnscaledValue().toString();
if (scale == 0) {
@@ -1517,7 +2390,21 @@
return result.toString();
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns a string representation of this {@code BigDecimal}. No scientific
+ * notation is used. This methods adds zeros where necessary.
+ * <p>
+ * If this string representation is used to create a new instance, this
+ * instance is generally not identical to {@code this} as the precision
+ * changes.
+ * <p>
+ * {@code x.equals(new BigDecimal(x.toPlainString())} usually returns
+ * {@code false}.
+ * <p>
+ * {@code x.compareTo(new BigDecimal(x.toPlainString())} returns {@code 0}.
+ *
+ * @return a string representation of {@code this} without exponent part.
+ */
public String toPlainString() {
String intStr = getUnscaledValue().toString();
if ((scale == 0) || ((isZero()) && (scale < 0))) {
@@ -1559,7 +2446,12 @@
return result.toString();
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns this {@code BigDecimal} as a big integer instance. A fractional
+ * part is discarded.
+ *
+ * @return this {@code BigDecimal} as a big integer instance.
+ */
public BigInteger toBigInteger() {
if ((scale == 0) || (isZero())) {
return getUnscaledValue();
@@ -1570,7 +2462,15 @@
}
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns this {@code BigDecimal} as a big integer instance if it has no
+ * fractional part. If this {@code BigDecimal} has a fractional part, i.e.
+ * if rounding would be necessary, an {@code ArithmeticException} is thrown.
+ *
+ * @return this {@code BigDecimal} as a big integer value.
+ * @throws ArithmeticException
+ * if rounding is necessary.
+ */
public BigInteger toBigIntegerExact() {
if ((scale == 0) || (isZero())) {
return getUnscaledValue();
@@ -1593,7 +2493,13 @@
}
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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.
+ */
@Override
public long longValue() {
/* If scale <= -64 there are at least 64 trailing bits zero in 10^(-scale).
@@ -1603,12 +2509,26 @@
: toBigInteger().longValue());
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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.
+ */
public long longValueExact() {
return valueExact(64);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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.
+ */
@Override
public int intValue() {
/* If scale <= -32 there are at least 32 trailing bits zero in 10^(-scale).
@@ -1618,22 +2538,64 @@
: toBigInteger().intValue());
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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.
+ */
public int intValueExact() {
return (int)valueExact(32);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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.
+ */
public short shortValueExact() {
return (short)valueExact(16);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns this {@code BigDecimal} as a byte value if it has no fractional
+ * 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);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns this {@code BigDecimal} as a float value. If {@code this} is too
+ * big to be represented as an float, then {@code Float.POSITIVE_INFINITY}
+ * or {@code Float.NEGATIVE_INFINITY} is returned.
+ * <p>
+ * Note, that if the unscaled value has more than 24 significant digits,
+ * then this decimal cannot be represented exactly in a float variable. In
+ * this case the result is rounded.
+ * <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.
+ * <p>
+ * Similarly, if the instance {@code new BigDecimal(16777217)} is converted
+ * to a float, the result is {@code 1.6777216E}7.
+ *
+ * @return this {@code BigDecimal} as a float value.
+ */
@Override
public float floatValue() {
/* A similar code like in doubleValue() could be repeated here,
@@ -1652,7 +2614,25 @@
return floatResult;
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Returns this {@code BigDecimal} as a double value. If {@code this} is too
+ * big to be represented as an float, then {@code Double.POSITIVE_INFINITY}
+ * or {@code Double.NEGATIVE_INFINITY} is returned.
+ * <p>
+ * Note, that if the unscaled value has more than 53 significant digits,
+ * then this decimal cannot be represented exactly in a double variable. In
+ * this case the result is rounded.
+ * <p>
+ * For example, if the instance {@code x1 = new BigDecimal("0.1")} cannot be
+ * represented exactly as a double, and thus {@code x1.equals(new
+ * BigDecimal(x1.doubleValue())} returns {@code false} for this case.
+ * <p>
+ * Similarly, if the instance {@code new BigDecimal(9007199254740993L)} is
+ * converted to a double, the result is {@code 9.007199254740992E15}.
+ * <p>
+ *
+ * @return this {@code BigDecimal} as a double value.
+ */
@Override
public double doubleValue() {
int sign = signum();
@@ -1754,7 +2734,21 @@
return Double.longBitsToDouble(bits);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * 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
+ * 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>
+ * For example, {@code new BigDecimal(0.1).ulp()} returns {@code 1E-55}.
+ *
+ * @return unit in the last place (ULP) of this {@code BigDecimal} instance.
+ */
public BigDecimal ulp() {
return valueOf(1, scale);
}
@@ -1762,15 +2756,18 @@
/* Private Methods */
/**
- * It does all rounding work of the public method <code>round(MathContext)</code>,
- * performing an inplace rounding without creating a new object.
- * @param mc the <code>MathContext</code> for perform the rounding.
- * @see #round(MathContext).
+ * It does all rounding work of the public method
+ * {@code round(MathContext)}, performing an inplace rounding
+ * without creating a new object.
+ *
+ * @param mc
+ * the {@code MathContext} for perform the rounding.
+ * @see #round(MathContext)
*/
private void inplaceRound(MathContext mc) {
- int mcPrecision = mc.getPrecision();
+ int mcPrecision = mc.getPrecision();
if (aproxPrecision() - mcPrecision <= 0 || mcPrecision == 0) {
- return;
+ return;
}
int discardedPrecision = precision() - mcPrecision;
// If no rounding is necessary it returns immediately
@@ -1816,11 +2813,14 @@
return value1 > value2 ? 1 : (value1 < value2 ? -1 : 0);
}
/**
- * This method implements an efficient rounding for numbers which unscaled
- * value fits in the type <code>long</code>.
- * @param mc the context to use.
- * @param discardedPrecision the number of decimal digits that are discarded.
- * @see #round(MathContext).
+ * This method implements an efficient rounding for numbers which unscaled
+ * value fits in the type {@code long}.
+ *
+ * @param mc
+ * the context to use
+ * @param discardedPrecision
+ * the number of decimal digits that are discarded
+ * @see #round(MathContext)
*/
private void smallRound(MathContext mc, int discardedPrecision) {
long sizeOfFraction = LONG_TEN_POW[discardedPrecision];
@@ -1853,11 +2853,17 @@
}
/**
- * Return an increment that can be -1,0 or 1, depending of <code>roundingMode</code>.
- * @param parityBit can be 0 or 1, it's only used in the case <code>HALF_EVEN</code>.
- * @param fraction the mantisa to be analyzed.
- * @param roundingMode the type of rounding.
- * @return the carry propagated after rounding.
+ * Return an increment that can be -1,0 or 1, depending of
+ * {@code roundingMode}.
+ *
+ * @param parityBit
+ * can be 0 or 1, it's only used in the case
+ * {@code HALF_EVEN}
+ * @param fraction
+ * the mantisa to be analyzed
+ * @param roundingMode
+ * the type of rounding
+ * @return the carry propagated after rounding
*/
private static int roundingBehavior(int parityBit, int fraction, RoundingMode roundingMode) {
int increment = 0; // the carry after rounding
@@ -1900,18 +2906,19 @@
}
/**
- * If <code>intVal</code> has a fractional part throws an exception,
- * otherwise it counts the number of bits of value and checks if it's out
- * of the range of the primitive type. If the number fits in the primitive
- * type returns this number as <code>long</code>, otherwise throws an
- * exception.
- *
- * @param bitLengthOfType number of bits of the type whose value will be
- * calculated exactly.
- * @return the exact value of the integer part of <code>BigDecimal</code>
- * when is possible.
- * @throws <code>ArithmeticException</code> when rounding is necessary or
- * the number don't fit in the primitive type.
+ * If {@code intVal} has a fractional part throws an exception,
+ * otherwise it counts the number of bits of value and checks if it's out of
+ * the range of the primitive type. If the number fits in the primitive type
+ * returns this number as {@code long}, otherwise throws an
+ * exception.
+ *
+ * @param bitLengthOfType
+ * number of bits of the type whose value will be calculated
+ * exactly
+ * @return the exact value of the integer part of {@code BigDecimal}
+ * when is possible
+ * @throws ArithmeticException when rounding is necessary or the
+ * number don't fit in the primitive type
*/
private long valueExact(int bitLengthOfType) {
BigInteger bigInteger = toBigIntegerExact();
@@ -1926,10 +2933,11 @@
/**
* If the precision already was calculated it returns that value, otherwise
- * it calculates a very good approximation efficiently . Note that this
- * value will be <code>precision()</code> or <code>precision()-1</code>
+ * it calculates a very good approximation efficiently . Note that this
+ * value will be {@code precision()} or {@code precision()-1}
* in the worst case.
- * @return an approximation of <code>precision()</code> value
+ *
+ * @return an approximation of {@code precision()} value
*/
private int aproxPrecision() {
return ((precision > 0)
@@ -1938,14 +2946,16 @@
}
/**
- * It tests if a scale of type <code>long</code> fits in 32 bits.
- * It returns the same scale being casted to <code>int</code> type when
- * is possible, otherwise throws an exception.
- * @param longScale a 64 bit scale.
- * @return a 32 bit scale when is possible.
- * @throws <code>ArithmeticException</code> when <code>scale</code>
- * doesn't fit in <code>int</code> type.
- * @see #scale
+ * It tests if a scale of type {@code long} fits in 32 bits. It
+ * returns the same scale being casted to {@code int} type when is
+ * possible, otherwise throws an exception.
+ *
+ * @param longScale
+ * a 64 bit scale
+ * @return a 32 bit scale when is possible
+ * @throws ArithmeticException when {@code scale} doesn't
+ * fit in {@code int} type
+ * @see #scale
*/
private static int toIntScale(long longScale) {
if (longScale < Integer.MIN_VALUE) {
@@ -1960,14 +2970,16 @@
}
/**
- * It returns the value 0 with the most approximated scale of type
- * <code>int</code>. if <code>longScale > Integer.MAX_VALUE</code>
- * the scale will be <code>Integer.MAX_VALUE</code>; if
- * <code>longScale < Integer.MIN_VALUE</code> the scale will be
- * <code>Integer.MIN_VALUE</code>; otherwise <code>longScale</code> is
- * casted to the type <code>int</code>.
- * @param longScale the scale to which the value 0 will be scaled.
- * @return the value 0 scaled by the closer scale of type <code>int</code>.
+ * It returns the value 0 with the most approximated scale of type
+ * {@code int}. if {@code longScale > Integer.MAX_VALUE} the
+ * scale will be {@code Integer.MAX_VALUE}; if
+ * {@code longScale < Integer.MIN_VALUE} the scale will be
+ * {@code Integer.MIN_VALUE}; otherwise {@code longScale} is
+ * casted to the type {@code int}.
+ *
+ * @param longScale
+ * the scale to which the value 0 will be scaled.
+ * @return the value 0 scaled by the closer scale of type {@code int}.
* @see #scale
*/
private static BigDecimal zeroScaledBy(long longScale) {
@@ -1980,7 +2992,11 @@
return new BigDecimal( 0, Integer.MIN_VALUE);
}
- /** @ar.org.fitc.spec_ref */
+ /**
+ * Assignes all transient fields upon deserialization of a
+ * {@code BigDecimal} instance (bitLength and smallValue). The transient
+ * field precision is assigned lazily.
+ */
private void readObject(ObjectInputStream in) throws IOException,
ClassNotFoundException {
in.defaultReadObject();
@@ -1991,6 +3007,10 @@
}
}
+ /**
+ * Prepares this {@code BigDecimal} for serialization, i.e. the
+ * non-transient field {@code intVal} is assigned.
+ */
private void writeObject(ObjectOutputStream out) throws IOException {
getUnscaledValue();
out.defaultWriteObject();