|
|
Class Description
|
|
|
Immutable, arbitrary-precision signed decimal numbers. A BigDecimal
consists of an arbitrary precision integer unscaled value and a
non-negative 32-bit integer scale, which represents the number of
digits to the right of the decimal point. The number represented by the
BigDecimal is (unscaledValue/10scale). 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(BigDecimal,int), divide(BigDecimal,int,int),
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, pseudo-code is used throughout the
descriptions of BigDecimal methods. The pseudo-code expression
(i + j) is shorthand for "a BigDecimal whose value is
that of the BigDecimal i plus that of the BigDecimal j."
The pseudo-code expression (i == j) is shorthand for
"true if and only if the BigDecimal i represents the same
value as the the BigDecimal j." Other pseudo-code expressions are
interpreted similarly.
Note: care should be exercised if BigDecimals are to be used as
keys in a java.util.SortedMap or elements in a java.util.SortedSet, as BigDecimal's natural ordering is
inconsistent with equals. See Comparable, java.util.SortedMap or java.util.SortedSet for more
information.
All methods and constructors for this class
throw NullPointerException when passed
a null object reference for any input parameter.
|
Class Variables
|
|
|
ROUND_UP
public static final int
Rounding mode to round away from zero. Always increments the
digit prior to a non-zero discarded fraction. Note that this rounding
mode never decreases the magnitude of the calculated value.
ROUND_DOWN
public static final int
Rounding mode to round towards zero. Never increments the digit
prior to a discarded fraction (i.e., truncates). Note that this
rounding mode never increases the magnitude of the calculated value.
ROUND_CEILING
public static final int
Rounding mode to round towards positive infinity. If the
BigDecimal is positive, behaves as for ROUND_UP; if negative,
behaves as for ROUND_DOWN. Note that this rounding mode never
decreases the calculated value.
ROUND_FLOOR
public static final int
Rounding mode to round towards negative infinity. If the
BigDecimal is positive, behave as for ROUND_DOWN; if negative,
behave as for ROUND_UP. Note that this rounding mode never
increases the calculated value.
ROUND_HALF_UP
public static final int
Rounding mode to round towards "nearest neighbor" unless both
neighbors are equidistant, in which case round up.
Behaves as for ROUND_UP if the discarded fraction is >= .5;
otherwise, behaves as for ROUND_DOWN. Note that this is the
rounding mode that most of us were taught in grade school.
ROUND_HALF_DOWN
public static final int
Rounding mode to round towards "nearest neighbor" unless both
neighbors are equidistant, in which case round down.
Behaves as for ROUND_UP if the discarded fraction is > .5;
otherwise, behaves as for ROUND_DOWN.
ROUND_HALF_EVEN
public static final int
Rounding mode to round towards the "nearest neighbor" unless both
neighbors are equidistant, in which case, round towards the even
neighbor. Behaves as for ROUND_HALF_UP if the digit to the left of the
discarded fraction is odd; behaves as for ROUND_HALF_DOWN if it's even.
Note that this is the rounding mode that minimizes cumulative error
when applied repeatedly over a sequence of calculations.
ROUND_UNNECESSARY
public static final int
Rounding mode to assert that the requested operation has an exact
result, hence no rounding is necessary. If this rounding mode is
specified on an operation that yields an inexact result, an
ArithmeticException is thrown.
|
Instance Variables
|
|
|
None declared in this class.
|
Constructors
|
|
|
BigDecimal
public BigDecimal(
BigInteger val
)
Translates a BigInteger into a BigDecimal. The scale of the BigDecimal
is zero.
BigDecimal
public BigDecimal(
BigInteger unscaledVal,
int scale
)
Translates a BigInteger unscaled value and an int
scale into a BigDecimal. The value of the BigDecimal is
(unscaledVal/10scale).
BigDecimal
public BigDecimal(
double val
)
Translates a double into a BigDecimal. The scale
of the BigDecimal is the smallest value such that
(10scale * val) is an integer.
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 notwithstanding.
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.
BigDecimal
public BigDecimal(
String val
)
Translates the String representation of a BigDecimal into a
BigDecimal. The String representation consists of an optional
sign, '+' ('\u002B') or '-'
('\u002D'), followed by a sequence of zero or more
decimal digits ("the integer"), optionally followed by a
fraction, optionally followed by an exponent.
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'
('\u0075') or 'E' ('\u0045')
followed by one or more decimal digits. The value of the
exponent must lie between -MAX_VALUE (MIN_VALUE+1) and MAX_VALUE, inclusive.
More formally, the strings this constructor accepts are
described by the following grammar:
- BigDecimalString:
- Signopt Significand Exponentopt
- Sign:
+
-
- Significand:
- IntegerPart
. FractionPartopt
. FractionPart
- IntegerPart
- IntegerPart:
- Digits
- FractionPart:
- Digits
- Exponent:
- ExponentIndicator SignedInteger
- ExponentIndicator:
e
E
- SignedInteger:
- Signopt Digits
- Digits:
- Digit
- Digits Digit
- Digit:
- any character for which isDigit
returns
true, including 0, 1, 2 ...
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 ×
10exponent. (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 character-to-digit mapping is provided by digit set to convert to radix 10. The
String may not contain any extraneous characters (whitespace,
for example).
Note: For values other float and double
NaN and ±Infinity, this constructor is compatible with
the values returned by toString and 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.
|
Class Methods
|
|
|
valueOf
public static BigDecimal valueOf(
long val
)
Translates a long value into a BigDecimal with a
scale of zero. This "static factory method" is provided in
preference to a (long) constructor because it
allows for reuse of frequently used BigDecimals.
valueOf
public static BigDecimal valueOf(
long unscaledVal,
int scale
)
Translates a long unscaled value and an
int scale into a BigDecimal. This "static factory
method" is provided in preference to a (long,
int) constructor because it allows for reuse of
frequently used BigDecimals.
|
Instance Methods
|
|
|
abs
public BigDecimal abs(
)
Returns a BigDecimal whose value is the absolute value of this
BigDecimal, and whose scale is this.scale().
add
public BigDecimal add(
BigDecimal val
)
Returns a BigDecimal whose value is (this + val), and whose
scale is max(this.scale(), val.scale()).
compareTo
public int compareTo(
BigDecimal val
)
Compares this BigDecimal with the specified BigDecimal. Two
BigDecimals that are equal in value but have a different scale (like
2.0 and 2.00) are considered equal by this method. This method is
provided in preference to individual methods for each of the six
boolean comparison operators (<, ==, >, >=, !=, <=). The
suggested idiom for performing these comparisons is:
(x.compareTo(y) <op> 0),
where <op> is one of the six comparison operators.
compareTo
public int compareTo(
Object o
)
Compares this BigDecimal with the specified Object. If the Object is a
BigDecimal, this method behaves like compareTo.
Otherwise, it throws a ClassCastException (as BigDecimals are
comparable only to other BigDecimals).
divide
public BigDecimal divide(
BigDecimal val,
int roundingMode
)
Returns a BigDecimal whose value is (this / val), and whose
scale is this.scale(). If rounding must be performed to
generate a result with the given scale, the specified rounding mode is
applied.
divide
public BigDecimal divide(
BigDecimal val,
int scale,
int roundingMode
)
Returns a BigDecimal whose value is (this / val), and whose
scale is as specified. If rounding must be performed to generate a
result with the specified scale, the specified rounding mode is
applied.
doubleValue
public double doubleValue(
)
Converts this BigDecimal to a double. This
conversion is similar to the narrowing
primitive conversion from double to
float as defined in the Java Language
Specification: if this BigDecimal has too great a magnitude
represent as a double, it will be converted to
NEGATIVE_INFINITY or POSITIVE_INFINITY as appropriate. Note that even when
the return value is finite, this conversion can lose
information about the precision of the BigDecimal value.
equals
public boolean equals(
Object x
)
Compares this BigDecimal with the specified Object for
equality. Unlike compareTo, this method
considers two BigDecimals equal only if they are equal in value
and scale (thus 2.0 is not equal to 2.00 when compared by this
method).
floatValue
public float floatValue(
)
Converts this BigDecimal to a float. This
conversion is similar to the narrowing
primitive conversion from double to
float defined in the Java Language
Specification: if this BigDecimal has too great a magnitude
to represent as a float, it will be converted to
NEGATIVE_INFINITY or POSITIVE_INFINITY as appropriate. Note that even when
the return value is finite, this conversion can lose
information about the precision of the BigDecimal value.
hashCode
public int hashCode(
)
Returns the hash code for this BigDecimal. Note that two BigDecimals
that are numerically equal but differ in scale (like 2.0 and 2.00)
will generally not have the same hash code.
intValue
public int intValue(
)
Converts this BigDecimal to an int. This
conversion is analogous to a narrowing
primitive conversion from double to
short as defined in the Java Language
Specification: any fractional part of this BigDecimal will
be discarded, and if the resulting "BigInteger" is
too big to fit in an int, only the low-order 32
bits are returned. Note that this conversion can lose
information about the overall magnitude and precision of the
BigDecimal value as well as return a result with the opposite
sign.
longValue
public long longValue(
)
Converts this BigDecimal to a long. This
conversion is analogous to a narrowing
primitive conversion from double to
short as defined in the Java Language
Specification: any fractional part of this BigDecimal will
be discarded, and if the resulting "BigInteger" is
too big to fit in a long, only the low-order 64
bits are returned. Note that this conversion can lose
information about the overall magnitude and precision of the
BigDecimal value as well as return a result with the opposite
sign.
max
public BigDecimal max(
BigDecimal val
)
Returns the maximum of this BigDecimal and val.
min
public BigDecimal min(
BigDecimal val
)
Returns the minimum of this BigDecimal and val.
movePointLeft
public BigDecimal movePointLeft(
int n
)
Returns a BigDecimal which is equivalent to this one with the decimal
point moved n places to the left. If n is non-negative, the call merely
adds n to the scale. If n is negative, the call is equivalent to
movePointRight(-n). (The BigDecimal returned by this call has value
(this * 10-n) and scale
max(this.scale()+n, 0).)
movePointRight
public BigDecimal movePointRight(
int n
)
Moves the decimal point the specified number of places to the right.
If this BigDecimal's scale is >= n, the call merely
subtracts n from the scale; otherwise, it sets the scale to
zero, and multiplies the integer value by
10(n - this.scale). If n
is negative, the call is equivalent to movePointLeft(-n). (The
BigDecimal returned by this call has value
(this * 10n) and scale
max(this.scale()-n, 0).)
multiply
public BigDecimal multiply(
BigDecimal val
)
Returns a BigDecimal whose value is (this * val), and whose
scale is (this.scale() + val.scale()).
negate
public BigDecimal negate(
)
Returns a BigDecimal whose value is (-this), and whose scale
is this.scale().
scale
public int scale(
)
Returns the scale of this BigDecimal. (The scale is the number
of digits to the right of the decimal point.)
setScale
public BigDecimal setScale(
int scale
)
Returns a BigDecimal whose scale is the specified value, and whose
value is numerically equal to this BigDecimal's. Throws an
ArithmeticException if this is not possible. This call is typically
used to increase the scale, in which case it is guaranteed that there
exists a BigDecimal of the specified scale and the correct value. The
call can also be used to reduce the scale if the caller knows that the
BigDecimal has sufficiently many zeros at the end of its fractional
part (i.e., factors of ten in its integer value) to allow for the
rescaling without loss of precision.
This method 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.
Note that since BigDecimal objects are immutable, calls of this
method do not result in the original object being
modified, contrary to the usual convention of having methods
named setX mutate field
X. Instead, setScale returns
an object with the proper scale; the returned object may or may
not be newly allocated.
setScale
public 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. If the scale is reduced by the operation, the
unscaled value must be divided (rather than multiplied), and the value
may be changed; in this case, the specified rounding mode is applied to
the division.
Note that since BigDecimal objects are immutable, calls of this
method do not result in the original object being
modified, contrary to the usual convention of having methods
named setX mutate field
X. Instead, setScale returns
an object with the proper scale; the returned object may or may
not be newly allocated.
signum
public int signum(
)
Returns the signum function of this BigDecimal.
subtract
public BigDecimal subtract(
BigDecimal val
)
Returns a BigDecimal whose value is (this - val), and whose
scale is max(this.scale(), val.scale()).
toBigInteger
public BigInteger toBigInteger(
)
Converts this BigDecimal to a BigInteger. This conversion is
analogous to a narrowing
primitive conversion from double to
long as defined in the Java Language
Specification: any fractional part of this BigDecimal will
be discarded. Note that this conversion can lose information
about the precision of the BigDecimal value.
toString
public String toString(
)
Returns the string representation of this BigDecimal. The digit-to-
character mapping provided by forDigit is used.
A leading minus sign is used to indicate sign, and the number of digits
to the right of the decimal point is used to indicate scale. (This
representation is compatible with the (String) constructor.)
unscaledValue
public BigInteger unscaledValue(
)
Returns a BigInteger whose value is the unscaled value of this
BigDecimal. (Computes (this * 10this.scale()).)
|
|
|