
Java^{TM} 2 Platform Std. Ed. v1.3 

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: INNER  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object  +java.lang.Number  +java.math.BigDecimal
Immutable, arbitraryprecision signed decimal numbers. A BigDecimal consists of an arbitrary precision integer unscaled value and a nonnegative 32bit integer scale, which represents the number of digits to the right of the decimal point. The number represented by the BigDecimal is (unscaledValue/10^{scale}). BigDecimal provides operations for basic arithmetic, scale manipulation, comparison, hashing, and format conversion.
The BigDecimal class gives its user complete control over rounding behavior, forcing the user to explicitly specify a rounding behavior for operations capable of discarding precision (divide and setScale). Eight rounding modes are provided for this purpose.
Two types of operations are provided for manipulating the scale of a BigDecimal: scaling/rounding operations and decimal point motion operations. Scaling/rounding operations (SetScale) return a BigDecimal whose value is approximately (or exactly) equal to that of the operand, but whose scale is the specified value; that is, they increase or decrease the precision of the number with minimal effect on its value. Decimal point motion operations (movePointLeft and movePointRight) return a BigDecimal created from the operand by moving the decimal point a specified distance in the specified direction; that is, they change a number's value without affecting its precision.
For the sake of brevity and clarity, pseudocode is used throughout the descriptions of BigDecimal methods. The pseudocode expression (i + j) is shorthand for "a BigDecimal whose value is that of the BigDecimal i plus that of the BigDecimal j." The pseudocode expression (i == j) is shorthand for "true if and only if the BigDecimal i represents the same value as the the BigDecimal j." Other pseudocode expressions are interpreted similarly.
Note: care should be exercised if BigDecimals are to be used as keys in a SortedMap or elements in a SortedSet, as BigDecimal's natural ordering is inconsistent with equals. See Comparable, SortedMap or SortedSet for more information.
BigInteger
,
SortedMap
,
SortedSet
, Serialized FormField Summary  
static int 
ROUND_CEILING
Rounding mode to round towards positive infinity. 
static int 
ROUND_DOWN
Rounding mode to round towards zero. 
static int 
ROUND_FLOOR
Rounding mode to round towards negative infinity. 
static int 
ROUND_HALF_DOWN
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. 
static int 
ROUND_HALF_EVEN
Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case, round towards the even neighbor. 
static int 
ROUND_HALF_UP
Rounding mode to round towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. 
static int 
ROUND_UNNECESSARY
Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary. 
static int 
ROUND_UP
Rounding mode to round away from zero. 
Constructor Summary  
BigDecimal(BigInteger val)
Translates a BigInteger into a BigDecimal. 

BigDecimal(BigInteger unscaledVal,
int scale)
Translates a BigInteger unscaled value and an int scale into a BigDecimal. 

BigDecimal(double val)
Translates a double into a BigDecimal. 

BigDecimal(String val)
Translates the String representation of a BigDecmal into a BigDecimal. 
Method Summary  
BigDecimal 
abs()
Returns a BigDecimal whose value is the absolute value of this BigDecimal, and whose scale is this.scale(). 
BigDecimal 
add(BigDecimal val)
Returns a BigDecimal whose value is (this + val), and whose scale is max(this.scale(), val.scale()). 
int 
compareTo(BigDecimal val)
Compares this BigDecimal with the specified BigDecimal. 
int 
compareTo(Object o)
Compares this BigDecimal with the specified Object. 
BigDecimal 
divide(BigDecimal val,
int roundingMode)
Returns a BigDecimal whose value is (this / val), and whose scale is this.scale(). 
BigDecimal 
divide(BigDecimal val,
int scale,
int roundingMode)
Returns a BigDecimal whose value is (this / val), and whose scale is as specified. 
double 
doubleValue()
Converts this BigDecimal to a double. 
boolean 
equals(Object x)
Compares this BigDecimal with the specified Object for equality. 
float 
floatValue()
Converts this BigDecimal to a float. 
int 
hashCode()
Returns the hash code for this BigDecimal. 
int 
intValue()
Converts this BigDecimal to an int. 
long 
longValue()
Converts this BigDecimal to a long. 
BigDecimal 
max(BigDecimal val)
Returns the maximum of this BigDecimal and val. 
BigDecimal 
min(BigDecimal val)
Returns the minimum of this BigDecimal and val. 
BigDecimal 
movePointLeft(int n)
Returns a BigDecimal which is equivalent to this one with the decimal point moved n places to the left. 
BigDecimal 
movePointRight(int n)
Moves the decimal point the specified number of places to the right. 
BigDecimal 
multiply(BigDecimal val)
Returns a BigDecimal whose value is (this * val), and whose scale is (this.scale() + val.scale()). 
BigDecimal 
negate()
Returns a BigDecimal whose value is (this), and whose scale is this.scale(). 
int 
scale()
Returns the scale of this BigDecimal. 
BigDecimal 
setScale(int scale)
Returns a BigDecimal whose scale is the specified value, and whose value is numerically equal to this BigDecimal's. 
BigDecimal 
setScale(int scale,
int roundingMode)
Returns a BigDecimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this BigDecimal's unscaled value by the appropriate power of ten to maintain its overall value. 
int 
signum()
Returns the signum function of this BigDecimal. 
BigDecimal 
subtract(BigDecimal val)
Returns a BigDecimal whose value is (this  val), and whose scale is max(this.scale(), val.scale()). 
BigInteger 
toBigInteger()
Converts this BigDecimal to a BigInteger. 
String 
toString()
Returns the string representation of this BigDecimal. 
BigInteger 
unscaledValue()
Returns a BigInteger whose value is the unscaled value of this BigDecimal. 
static BigDecimal 
valueOf(long val)
Translates a long value into a BigDecimal with a scale of zero. 
static BigDecimal 
valueOf(long unscaledVal,
int scale)
Translates a long unscaled value and an int scale into a BigDecimal. 
Methods inherited from class java.lang.Number 
byteValue, shortValue 
Methods inherited from class java.lang.Object 
clone, finalize, getClass, notify, notifyAll, wait, wait, wait 
Field Detail 
public static final int ROUND_UP
public static final int ROUND_DOWN
public static final int ROUND_CEILING
public static final int ROUND_FLOOR
public static final int ROUND_HALF_UP
public static final int ROUND_HALF_DOWN
public static final int ROUND_HALF_EVEN
public static final int ROUND_UNNECESSARY
Constructor Detail 
public BigDecimal(String val)
The fraction consists of of a decimal point followed by zero or more decimal digits. The string must contain at least one digit in either the integer or the fraction. The number formed by the sign, the integer and the fraction is referred to as the significand.
The exponent consists of the character 'e'(0x75) or E (0x45) followed by one or more decimal digits. The value of the exponenet must lie between Integer.MIN_VALUE and Integer.MAX_VALUE, inclusive.
The scale of the returned BigDecimal will be the number of digits in the fraction, or zero if the string contains no decimal point, subject to adjustment for any exponent: If the string contains an exponent, the exponent is subtracted from the scale. If the resulting scale is negative, the scale of the returned BigDecimal is zero and the unscaled value is multiplied by the appropriate power of ten so that, in every case, the resulting BigDecimal is equal to significand * 10^{exponent}. (If in the future this specification is amended to permit negative scales, the final step of zeroing the scale and adjusting the unscaled value will be eliminated.)
The charactertodigit mapping is provided by Character.digit(char, int)
. The String may not contain any extraneous
characters (whitespace, for example).
Note: For floats (and doubles) other that NAN, +INFINITY and
INFINITY, this constructor is compatible with the values returned by
Float.toString (and Double.toString). This is
generally the preferred way to convert a float (or double) into a
BigDecimal, as it doesn't suffer from the unpredictability of the
BigDecimal(double)
constructor.
Note: the optional leading plus sign and trailing exponent were added in release 1.3.
val
 String representation of BigDecimal.NumberFormatException
 val is not a valid representation
of a BigDecimal.public BigDecimal(double val)
Note: the results of this constructor can be somewhat unpredictable. One might assume that new BigDecimal(.1) is exactly equal to .1, but it is actually equal to .1000000000000000055511151231257827021181583404541015625. This is so because .1 cannot be represented exactly as a double (or, for that matter, as a binary fraction of any finite length). Thus, the long value that is being passed in to the constructor is not exactly equal to .1, appearances nonwithstanding.
The (String) constructor, on the other hand, is perfectly predictable: new BigDecimal(".1") is exactly equal to .1, as one would expect. Therefore, it is generally recommended that the (String) constructor be used in preference to this one.
val
 double value to be converted to BigDecimal.NumberFormatException
 val is equal to
Double.NEGATIVE_INFINITY,
Double.POSITIVE_INFINITY, or Double.NaN.public BigDecimal(BigInteger val)
val
 BigInteger value to be converted to BigDecimal.public BigDecimal(BigInteger unscaledVal, int scale)
unscaledVal
 unscaled value of the BigDecimal.scale
 scale of the BigDecimal.NumberFormatException
 scale is negativeMethod Detail 
public static BigDecimal valueOf(long unscaledVal, int scale)
unscaledVal
 unscaled value of the BigDecimal.scale
 scale of the BigDecimal.public static BigDecimal valueOf(long val)
val
 value of the BigDecimal.public BigDecimal add(BigDecimal val)
val
 value to be added to this BigDecimal.public BigDecimal subtract(BigDecimal val)
val
 value to be subtracted from this BigDecimal.public BigDecimal multiply(BigDecimal val)
val
 value to be multiplied by this BigDecimal.public BigDecimal divide(BigDecimal val, int scale, int roundingMode)
val
 value by which this BigDecimal is to be divided.scale
 scale of the BigDecimal quotient to be returned.roundingMode
 rounding mode to apply.ArithmeticException
 val is zero, scale is
negative, or roundingMode==ROUND_UNNECESSARY and
the specified scale is insufficient to represent the result
of the division exactly.IllegalArgumentException
 roundingMode does not
represent a valid rounding mode.ROUND_UP
,
ROUND_DOWN
,
ROUND_CEILING
,
ROUND_FLOOR
,
ROUND_HALF_UP
,
ROUND_HALF_DOWN
,
ROUND_HALF_EVEN
,
ROUND_UNNECESSARY
public BigDecimal divide(BigDecimal val, int roundingMode)
val
 value by which this BigDecimal is to be divided.roundingMode
 rounding mode to apply.ArithmeticException
 val==0, or
roundingMode==ROUND_UNNECESSARY and
this.scale() is insufficient to represent the result
of the division exactly.IllegalArgumentException
 roundingMode does not
represent a valid rounding mode.ROUND_UP
,
ROUND_DOWN
,
ROUND_CEILING
,
ROUND_FLOOR
,
ROUND_HALF_UP
,
ROUND_HALF_DOWN
,
ROUND_HALF_EVEN
,
ROUND_UNNECESSARY
public BigDecimal abs()
public BigDecimal negate()
public int signum()
public int scale()
public BigInteger unscaledValue()
public BigDecimal setScale(int scale, int roundingMode)
scale
 scale of the BigDecimal value to be returned.roundingMode
 The rounding mode to apply.ArithmeticException
 scale is negative, or
roundingMode==ROUND_UNNECESSARY and the specified
scaling operation would require rounding.IllegalArgumentException
 roundingMode does not
represent a valid rounding mode.ROUND_UP
,
ROUND_DOWN
,
ROUND_CEILING
,
ROUND_FLOOR
,
ROUND_HALF_UP
,
ROUND_HALF_DOWN
,
ROUND_HALF_EVEN
,
ROUND_UNNECESSARY
public BigDecimal setScale(int scale)
Note that this call returns the same result as the two argument version of setScale, but saves the caller the trouble of specifying a rounding mode in cases where it is irrelevant.
scale
 scale of the BigDecimal value to be returned.ArithmeticException
 scale is negative, or
the specified scaling operation would require rounding.setScale(int, int)
public BigDecimal movePointLeft(int n)
n
 number of places to move the decimal point to the left.public BigDecimal movePointRight(int n)
n
 number of places to move the decimal point to the right.public int compareTo(BigDecimal val)
val
 BigDecimal to which this BigDecimal is to be compared.public int compareTo(Object o)
compareTo
in interface Comparable
o
 Object to which this BigDecimal is to be compared.ClassCastException
 o is not a BigDecimal.compareTo(java.math.BigDecimal)
,
Comparable
public boolean equals(Object x)
equals
in class Object
x
 Object to which this BigDecimal is to be compared.compareTo(java.math.BigDecimal)
public BigDecimal min(BigDecimal val)
val
 value with with the minimum is to be computed.compareTo(java.math.BigDecimal)
public BigDecimal max(BigDecimal val)
val
 value with with the maximum is to be computed.compareTo(java.math.BigDecimal)
public int hashCode()
hashCode
in class Object
public String toString()
toString
in class Object
Character.forDigit(int, int)
,
BigDecimal(java.lang.String)
public BigInteger toBigInteger()
public int intValue()
intValue
in class Number
public long longValue()
longValue
in class Number
public float floatValue()
floatValue
in class Number
public double doubleValue()
doubleValue
in class Number

Java^{TM} 2 Platform Std. Ed. v1.3 

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: INNER  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 19932000 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.