Index: modules/math/src/main/java/java/math/BigInteger.java =================================================================== --- modules/math/src/main/java/java/math/BigInteger.java.orig 2006-03-29 21:59:08.000000000 +0100 +++ modules/math/src/main/java/java/math/BigInteger.java 2006-03-29 21:59:11.000000000 +0100 @@ -27,7 +27,9 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * BigInteger objects represent arbitrary precision decimal integers. They + * contain values that cannot be changed. Thus, most operations on the + * BigInteger objects yield new instances of BigInteger. */ public class BigInteger extends Number implements Comparable, Serializable { private static final int EQUALS = 0; @@ -598,16 +600,26 @@ return res; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new instance of this class whose value is greater + * than zero, length is the given number of bits, and whose + * likeyhood of being prime is not less than 2 ^ -100. + * + * @param length + * the number of bits contained in the returned instance. + * @param rand + * a random source of bits for selection of the probable prime. + * @return the probable prime number. + */ public static BigInteger probablePrime(int length, Random rand) { return new BigInteger(length, 100, rand); } - - /** - * @com.intel.drl.spec_ref - */ + + /** + * Answers a BigInteger with the same value as longValue + * + * @return BigInteger (BigInteger) longValue + */ public static BigInteger valueOf(long longValue) { int valueSign = (longValue > 0 ? 1 : longValue < 0 ? -1 : 0); if (longValue < 0) { @@ -635,9 +647,14 @@ digits = value; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class given an array + * containing bytes representing the bit pattern for the + * answer. + * + * @param byteValues + * byte[] the bits of the value of the new instance. + */ public BigInteger(byte[] byteValues) { if (byteValues.length == 0) { throw new NumberFormatException("zero length array"); @@ -652,9 +669,16 @@ cutOffLeadingZeroes(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class given an array + * containing bytes representing the bit pattern for the + * answer, and a sign flag. + * + * @param signum + * int the sign of the result. + * @param byteValues + * byte[] the bits of the value of the new instance. + */ public BigInteger(int signum, byte[] byteValues) { if (signum < -1 || signum > 1) { throw new NumberFormatException("sign must be -1, 0, or 1"); @@ -680,9 +704,16 @@ digits[0] = 0; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class of the specified + * length, whose content is produced by acquiring random bits + * from the specified random number generator. + * + * @param numberBitLength + * int the number of bits to have in the result. + * @param rand + * Random the generator to produce the bits. + */ public BigInteger(int numberBitLength, Random rand) { if (numberBitLength < 0) { throw new IllegalArgumentException("negative bit length"); @@ -690,10 +721,20 @@ boolean stripLeadingZeroes = true; constructRandomly(numberBitLength, rand, stripLeadingZeroes); } - - /** - * @com.intel.drl.spec_ref - */ + + /** + * Constructs a new instance of this class of the specified + * length, whose content is produced by acquiring random bits + * from the specified random number generator. The result is + * guaranteed to be prime up to the given degree of certainty. + * + * @param numberBitLength + * int the number of bits to have in the result. + * @param certainty + * int the degree of certainty required that the result is prime. + * @param rand + * Random the generator to produce the bits. + */ public BigInteger(int numberBitLength, int certainty, Random rand) { if (numberBitLength < 2) { throw new ArithmeticException("bit length is less than 2"); @@ -714,16 +755,26 @@ } while (!isProbablePrime(certainty)); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class given a string containing a + * representation of a decimal number. + * + * @param value + * String the decimal digits of the answer. + */ public BigInteger(String value) { this(value, 10); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class given a string + * containing digits in the specified radix. + * + * @param stringValue + * String the digits of the answer. + * @param radix + * int the radix to use for conversion. + */ public BigInteger(String stringValue, int radix) { if (radix < Character.MIN_RADIX || radix > Character.MAX_RADIX) { throw new NumberFormatException("radix is out of range"); @@ -782,9 +833,11 @@ cutOffLeadingZeroes(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the absolute value of the receiver + * + * @return BigInteger absolute value of the receiver + */ public BigInteger abs() { if (this.sign >= 0) { return this; @@ -792,9 +845,14 @@ return new BigInteger(1, numberLength, digits); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the sum of the receiver and a BigInteger + * + * @param that + * a BigInteger to add + * + * @return BigInteger this + that + */ public BigInteger add(BigInteger that) { int resDigits[]; int resSign; @@ -831,9 +889,13 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the bitwise AND of the receiver and the argument. + * + * @param that + * BigInteger the value to AND. + * @return BigInteger this & that + */ public BigInteger and(BigInteger that) { if (this.sign == 0 || that.sign == 0) { return ZERO; @@ -933,16 +995,22 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the bitwise NAND of the receiver and the argument. + * + * @param that + * BigInteger the value to NAND. + * @return BigInteger this & NOT(that) + */ public BigInteger andNot(BigInteger that) { return and(that.not()); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the number of set bits in the receiver. + * + * @return int the receiver's bit count. + */ public int bitCount() { if (sign == 0) { return 0; @@ -979,9 +1047,11 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the length in bits of the receiver. + * + * @return int the receiver's bit length. + */ public int bitLength() { if (sign == 0) { return 0; @@ -1060,9 +1130,12 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Unsets the specified bit in the receiver. + * + * @param bitNumber + * int the bit to clear. + */ public BigInteger clearBit(int bitNumber) { if (bitNumber < 0) { throw new ArithmeticException("negative bit number"); @@ -1075,9 +1148,20 @@ return changeBit(intCount, bitNumber, 3); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer indicating the relative positions of the receiver and + * the argument in the natural order of elements of the receiver's class. + * + * @return int which should be <0 if the receiver should sort before the + * argument, 0 if the receiver should sort in the same position as + * the argument, and >0 if the receiver should sort after the + * argument. + * @param that + * BigInteger an object to compare the receiver to + * @exception ClassCastException + * if the argument can not be converted into something + * comparable with the receiver. + */ public int compareTo(BigInteger that) { if (this.sign == that.sign) { int compareResult = compareMagnitude(this.digits, @@ -1094,9 +1178,20 @@ return this.sign; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer indicating the relative positions of the receiver and + * the argument in the natural order of elements of the receiver's class. + * + * @return int which should be <0 if the receiver should sort before the + * argument, 0 if the receiver should sort in the same position as + * the argument, and >0 if the receiver should sort after the + * argument. + * @param obj + * Object an object to compare the receiver to + * @exception ClassCastException + * if the argument can not be converted into something + * comparable with the receiver. + */ public int compareTo(Object obj) { if (obj instanceof BigInteger) { return (this.compareTo((BigInteger)obj)); @@ -1142,9 +1237,16 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the quotient of the receiver and a BigInteger. + * + * @param that + * BigInteger the value to divide + * @return BigInteger this / that + * + * @exception ArithmeticException + * if that is zero. + */ public BigInteger divide(BigInteger that) { if (that.equals(ZERO)) { throw new ArithmeticException("division by zero"); @@ -1179,9 +1281,17 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the quotient and remainder of the receiver divided by a + * BigInteger. + * + * @param that + * BigInteger the value to divide. + * @return BigInteger[2] {this / that, this % that )} + * + * @exception ArithmeticException + * if val is zero. + */ public BigInteger[] divideAndRemainder(BigInteger that) { if (that.isZero()) { throw new ArithmeticException("division by zero"); @@ -1236,9 +1346,11 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the double value which the receiver represents + * + * @return double the value of the receiver. + */ public double doubleValue() { if (sign == 0) { return 0.0; @@ -1282,9 +1394,18 @@ return Double.longBitsToDouble(result); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. In this + * case the argument must also be a BigInteger which represents the same + * number + * + * @param anotherObj + * Object the object to compare with this object. + * @return boolean true if the object is the same as this + * object false if it is different from this object. + * @see #hashCode + */ public boolean equals(Object anotherObj) { if (! (anotherObj instanceof BigInteger)) { return false; @@ -1292,9 +1413,12 @@ return (compareTo((BigInteger)anotherObj) == EQUALS ? true : false); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Toggles the specified bit in the receiver. + * + * @param bitNumber + * int the bit to flip. + */ public BigInteger flipBit(int bitNumber) { if (bitNumber < 0) { throw new ArithmeticException("negative bit number"); @@ -1304,16 +1428,21 @@ return changeBit(intCount, bitNumber, 1); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the float value which the receiver represents + * + * @return float the value of the receiver. + */ public float floatValue() { return (float)doubleValue(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the greatest common divisor of abs(this) and abs(val), zero if + * this==val==0 + * + * @return BigInteger gcd(abs(this), abs(that)) + */ public BigInteger gcd(BigInteger that) { if (this.isZero()) { return that.abs(); @@ -1333,9 +1462,13 @@ return secondNumber; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the index of the lowest set bit in the receiver, or -1 if no bits + * are set. + * + * @return BigInteger the bit index of the least significant set bit in the + * receiver. + */ public int getLowestSetBit() { if (this.isZero()) { return -1; @@ -1351,9 +1484,15 @@ return (intCount << 5) + bitCount; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to .equals must + * answer the same value for this method. + * + * @return int the receiver's hash. + * + * @see #equals + */ public int hashCode() { int hashCode = digits[0]; if (numberLength > 1) { @@ -1365,9 +1504,11 @@ return (sign == 1 ? hashCode : -hashCode); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the int value which the receiver represents + * + * @return int the value of the receiver. + */ public int intValue() { return (sign < 0 ? -digits[0] : digits[0]); } @@ -1382,9 +1523,14 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers true if the receiver is probably prime to the given degree of + * certainty. + * + * @param security + * int the degree of certainty required. + * @return boolean true if the receiver is prime and false otherwise. + */ public boolean isProbablePrime(int security) { if (security <= 0) { return true; @@ -1477,10 +1623,12 @@ } return false; } - - /** - * @com.intel.drl.spec_ref - */ + + /** + * Answers the long value which the receiver represents + * + * @return long the value of the receiver. + */ public long longValue() { long value = (long)digits[0] & 0xffffffffL; if (numberLength == 1) { @@ -1491,9 +1639,13 @@ return (sign < 0 ? -value : value); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the most positive of either the receiver or the argument. + * + * @param that + * BigInteger the value to compare. + * @return BigInteger the larger value. + */ public BigInteger max(BigInteger that) { if (compareTo(that) > 0) { return this; @@ -1502,9 +1654,13 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the most negative of either the receiver or the argument. + * + * @param that + * BigInteger the value to compare. + * @return BigInteger the smaller value. + */ public BigInteger min(BigInteger that) { if (compareTo(that) < 0) { return this; @@ -1513,9 +1669,17 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the remainder of the receiver modulo a BigInteger (a positive + * value). + * + * @param modulus + * the value to divide + * @return BigInteger this (mod modulus) + * + * @exception ArithmeticException + * if modulus is zero + */ public BigInteger mod(BigInteger modulus) { if (modulus.sign <= 0) { throw new ArithmeticException("modulus is non-positive"); @@ -1527,9 +1691,16 @@ return res; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the inverse of the receiver modulo a BigInteger, if it exists. + * + * @param m + * BigInteger a BigInteger to divide + * @return BigInteger this^(-1) (mod m) + * + * @exception ArithmeticException + * if m is <= 0, or gcd(this,m) != 1 + */ public BigInteger modInverse(BigInteger m) { // implements the extended Euclidean algorithm if (m.sign <= 0) { @@ -1568,10 +1739,15 @@ } return a; } - - /** - * @com.intel.drl.spec_ref - */ + + /** + * Answers the receiver to the power of exponent modulo a BigInteger + * + * @exception ArithmeticException + * modulus is <= 0 + * + * @return BigInteger this ^ exp (mod modulus) + */ public BigInteger modPow(BigInteger exp, BigInteger modulus) { // The square-and-multiply algorithm is used from // Handbook of Applied Cryptography, Alfred Menezes et al., p. 2.4. @@ -1596,9 +1772,13 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the product of the receiver and a BigInteger. + * + * @param that + * BigInteger the value to multiply + * @return BigInteger this * that + */ public BigInteger multiply(BigInteger that) { if (that.sign == 0 || this.sign == 0) { return ZERO; @@ -1653,9 +1833,11 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the negative of the receiver + * + * @return BigInteger (-1) * this + */ public BigInteger negate() { return new BigInteger(-sign, numberLength, digits); } @@ -1683,9 +1865,11 @@ } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the bitwise negation of the receiver. + * + * @return BigInteger NOT(this) + */ public BigInteger not() { // one extra element for possible carry returned from setTrueCoded int resLength = this.numberLength + 1; @@ -1704,9 +1888,13 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the bitwise OR of the receiver and the argument. + * + * @param that + * BigInteger the value to OR. + * @return BigInteger this | that + */ public BigInteger or(BigInteger that) { if (this.sign == 0) { return that; @@ -1805,9 +1993,14 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the receiver to the power of exponent. + * + * @exception ArithmeticException + * if the exp is negative. + * + * @return BigInteger this ^ exp + */ public BigInteger pow(int exp) { if (exp < 0) { throw new ArithmeticException("exponent is negative"); @@ -1849,9 +2042,17 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the remainder of the receiver divided by a BigInteger + * + * @param that + * a BigInteger to divide + * + * @exception ArithmeticException + * if that is zero + * + * @return BigInteger this % that + */ public BigInteger remainder(BigInteger that) { if (that.equals(ZERO)) { throw new ArithmeticException("division by zero"); @@ -1875,9 +2076,12 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Sets the specified bit in the receiver. + * + * @param number + * int the bit to set. + */ public BigInteger setBit(int number) { if (number < 0) { throw new ArithmeticException("negative bit number"); @@ -1890,16 +2094,24 @@ return changeBit(intCount, number, 2); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the sign of the receiver + * + * @return BigInteger -1, 0, or 1 if the receiver is negative, zero, or + * positive + */ public int signum() { return this.sign; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a BigInteger with the value of the reciever multiplied by + * 2^count. + * + * @param count + * int the amount to shift the receiver. + * @return BigInteger this << count + */ public BigInteger shiftLeft(int count) { if (count == 0) { return this; @@ -1926,9 +2138,14 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a BigInteger with the value of the reciever divided by + * 2^count. + * + * @param count + * int the amount to shift the receiver. + * @return BigInteger this >> count + */ public BigInteger shiftRight(int count) { if (count == 0) { return this; @@ -1971,9 +2188,13 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the difference of the receiver and a BigInteger. + * + * @param that + * BigInteger the value to subtract + * @return BigInteger this - that + */ public BigInteger subtract(BigInteger that) { int resSign; int resDigits[]; @@ -2005,9 +2226,13 @@ return result; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers true if the specified bit is set in the receiver. + * + * @param number + * int the bit to check. + * @return boolean if the specified bit is set. + */ public boolean testBit(int number) { if (number < 0) { throw new ArithmeticException("negative bit number"); @@ -2026,9 +2251,12 @@ return ((digits[intCount] & number) == number); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an array of bytes containing the value of the receiver in the + * same format used by the matching constructor. + * + * @return byte[] the bits of the value of the receiver. + */ public byte[] toByteArray() { int bytesLen; int bitLen = bitLength(); @@ -2080,16 +2308,22 @@ return bytes; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. In this case, a string of decimal digits. + * + * @return String a printable representation for the receiver. + */ public String toString() { return toString(10); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver as a sequence of digits in the specified radix. + * + * @return String a printable representation for the receiver. + */ public String toString(int radix) { if (sign == 0) { return "0"; @@ -2153,9 +2387,13 @@ return result.toString(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the bitwise XOR of the receiver and the argument. + * + * @param that + * BigInteger the value to XOR. + * @return BigInteger this XOR that + */ public BigInteger xor(BigInteger that) { if (this.sign == 0) { return that; Index: modules/math/src/main/java/java/math/BigDecimal.java =================================================================== --- modules/math/src/main/java/java/math/BigDecimal.java.orig 2006-03-29 21:59:08.000000000 +0100 +++ modules/math/src/main/java/java/math/BigDecimal.java 2006-03-29 21:59:11.000000000 +0100 @@ -26,7 +26,17 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * BigDecimal objects represent an arbitrary precisioned decimal Number. They + * contain values that cannot be changed. Thus, most operations on the + * BigDecimal object yield new instances of BigDecimal. + *

+ * BigDecimal is respresented by an unscaled BigInteger value and an integer + * representing the scale of the object. The scale of the BigDecimal is the + * number of digits after the decimal point. Eg. 1.234 would have a scale of 3 + * and an unscaled value of 1234. Therefore, decimal representation of a + * BigDecimal is BigIntegerValue/10^scale. + * + * @see java.math.BigInteger */ public class BigDecimal extends Number implements Comparable, Serializable { @@ -113,39 +123,50 @@ return (int)longVal; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Translate long value into a BigDecimal with scale of zero. + * + * @return BigDecimal BigDecimal equivalence of a long value. + */ public static BigDecimal valueOf(long value) { return valueOf(value, 0); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Translate long unscaled value into a BigDecimal specified by the scale. + * + * @return BigDecimal BigDecimal equalvalence of a long value. + * @exception NumberFormatException + * the scale value is < 0; + */ public static BigDecimal valueOf(long unscaledValue, int scale) { return new BigDecimal(BigInteger.valueOf(unscaledValue), scale); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a BigDecimal with unscaled value initialized as value and scale + * as 0. + */ public BigDecimal(BigInteger value) { intVal = value; scale = 0; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a BigDecimal with unscaled value initialized as unScaledValue and scale + * as scale from the argument. + */ public BigDecimal(BigInteger unScaledValue, int scale) { intVal = unScaledValue; this.scale = scale; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a BigDecimal with a double value as an arugment. + * + * @exception NumberFormatException + * If the is Infinity, Negative Infinity or NaN. + */ public BigDecimal(double value) { if (value != value) { throw new NumberFormatException ("argument is NaN"); @@ -180,9 +201,13 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a BigDecimal from the string which can only + * contain digits of 0-9, a decimal point and a negative sign. + * + * @exception NumberFormatException + * If the argument contained characters other than digits. + */ public BigDecimal(String value) { int count; // the significand's length int dotPlace = -1; @@ -242,16 +267,20 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the absolute value of this BigDecimal. + * + * @return BigDecimal absolute value of the receiver. + */ public BigDecimal abs() { return new BigDecimal(intVal.abs(), this.scale); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the sum of the receiver and argument. + * + * @return BigDecimal The sum of adding two BigDecimal. + */ public BigDecimal add(BigDecimal value) { if (scale == value.scale) { return new BigDecimal(intVal.add(value.intVal), scale); @@ -267,9 +296,12 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the receiver BigDecimal and argument BigDecimal e.x 1.00 & 1.0 + * will return 0 in compareTo. + * + * @return int 0 - equal; 1 - this > value; -1 - this < value. + */ public int compareTo(BigDecimal value) { if (this.scale == value.scale) { return this.intVal.compareTo(value.intVal); @@ -283,9 +315,13 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares an receiver to the argument Object. + * + * @return int 0 - equal; 1 - this > object; -1 - this < object + * @exception ClassCastException + * if the argument is not of type BigDecimal + */ public int compareTo(Object object) { if (object instanceof BigDecimal) { return (this.compareTo((BigDecimal)object)); @@ -293,16 +329,24 @@ throw new ClassCastException("BigDecimals are comparable only with other BigDecimals"); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the result of (this / value). + * + * @return BigDecimal result of this/value. + */ public BigDecimal divide(BigDecimal value, int roundingMode) { return divide(value, this.scale, roundingMode); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the result of (this / value) and whose scale is specified. + * + * @return BigDecimal result of this/value. + * @exception ArithmeticException + * division by zero. + * @exception IllegalArgumentException + * roundingMode is not valid. + */ public BigDecimal divide(BigDecimal value, int quotientScale, int roundingMode) { if (roundingMode > 7 || roundingMode < 0) { throw new IllegalArgumentException("invalid rounding mode"); @@ -368,60 +412,91 @@ return new BigDecimal(quotient, quotientScale); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Converts this BigDecimal to a double. If magnitude of the BigDecimal + * value is larger than what can be represented by a double, either Infinity + * or -Infinity is returned. + * + * @return double the value of the receiver. + */ public double doubleValue() { return Double.valueOf(toString()).doubleValue(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. The + * implementation in Object answers true only if the argument is the exact + * same object as the receiver (==). + * + * @param o + * Object the object to compare with this object. + * @return boolean true if the object is the same as this + * object false if it is different from this object. + * @see hashCode + */ public boolean equals(Object object) { return (object instanceof BigDecimal && this.compareTo(object) == 0 && this.scale == ((BigDecimal)object).scale); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Converts this BigDecimal to a float.If magnitude of the BigDecimal value + * is larger than what can be represented by a float, either Infinity or + * -Infinity is returned. + * + * @return float the value of the receiver. + */ public float floatValue() { return Float.valueOf(toString()).floatValue(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to .equals must + * answer the same value for this method. + * + * @return int the receiver's hash. + * + * @see #equals(Object) + */ public int hashCode() { return intVal.intValue() + scale; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Converts this BigDecimal to an int. + * + * @return int the value of the receiver. + */ public int intValue() { return toBigInteger().intValue(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Converts this BigDecimal to a long. + * + * @return long long representation of the receiver. + */ public long longValue() { return toBigInteger().longValue(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the max value between the receiver and this BigDecimal. + * + * @return BigDecimal max BigDecimal. + */ public BigDecimal max(BigDecimal value) { return (this.compareTo(value) >= 0 ? this : value); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the min value between the receiver and argument. + * + * @return BigDecimal min BigDecimal. + */ public BigDecimal min(BigDecimal value) { return (this.compareTo(value) <= 0 ? this : value); } @@ -438,52 +513,74 @@ return new BigDecimal(this.intVal.multiply(BigInteger.TEN.pow(-newScale)), 0); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Moves the decimal point of this BigDecimal n places to the left. + * + * @return BigDecimal new BigDecimal with decimal moved n places to the + * left. + */ public BigDecimal movePointLeft(int shift) { return movePoint(shift); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Moves the decimal point of this BigDecimal n places to the right. + * + * @return BigDecimal new BigDecimal with decimal moved n places to the + * right. + */ public BigDecimal movePointRight(int shift) { return movePoint(-shift); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the multiplication result of the receiver and argument. + * + * @return BigDecimal result of multiplying two bigDecimals. + */ public BigDecimal multiply(BigDecimal value) { return new BigDecimal(this.intVal.multiply(value.intVal), this.scale + value.scale); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Negates this BigDecimal value. + * + * @return BigDecimal new BigDecimal with value negated. + */ public BigDecimal negate() { return new BigDecimal(intVal.negate(), scale); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns the scale of this BigDecimal. + * + * @return int scale value. + */ public int scale() { return scale; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Sets the scale of this BigDecimal. + * + * @return BigDecimal a BigDecimal with the same value, but specified scale. + */ public BigDecimal setScale(int newScale) { return setScale(newScale, ROUND_UNNECESSARY); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Sets the scale of this BigDecimal. The unscaled value is determined by + * the rounding Mode + * + * @return BigDecimal a BigDecimal with the same value, but specified cale. + * @exception ArithmeticException + * rounding mode must be specified if lose of precision due + * to setting scale. + * @exception IllegalArgumentException + * invalid rounding mode + */ public BigDecimal setScale(int newScale, int roundingMode) { int delta = this.scale - newScale; if (delta == 0) { @@ -496,16 +593,20 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the signum function of this instance. + * + * @return int -1, 0, or 1 if the receiver is negative, zero, or positive. + */ public int signum() { return intVal.signum(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the subtract result of the receiver and argument. + * + * @return BigDecimal The result of subtracting the BigDecimal argument. + */ public BigDecimal subtract(BigDecimal value) { if (scale == value.scale) { return new BigDecimal(intVal.subtract(value.intVal), scale); @@ -521,9 +622,11 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Converts this to a BigInteger. + * + * @return BigInteger BigDecimal equivalent of BigInteger. + */ public BigInteger toBigInteger() { if (scale == 0) { return intVal; @@ -570,9 +673,12 @@ return result.toString(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return String a printable representation for the receiver. + */ public String toString() { String intString = intVal.toString(); if (scale == 0) { @@ -610,9 +716,11 @@ return result.toString(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns an unscaled value of this BigDecimal. + * + * @return BigInteger The unscaled value. + */ public BigInteger unscaledValue() { return intVal; } @@ -626,4 +734,4 @@ throw new StreamCorruptedException("null unscaled value"); } } -} \ No newline at end of file +}