Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Number
com.ibm.icu.math.BigDecimal
BigDecimal
class implements immutable
arbitrary-precision decimal numbers. The methods of the
BigDecimal
class provide operations for fixed and
floating point arithmetic, comparison, format conversions, and
hashing.
As the numbers are decimal, there is an exact correspondence between
an instance of a BigDecimal
object and its
String
representation; the BigDecimal
class
provides direct conversions to and from String
and
character array (char[]
) objects, as well as conversions
to and from the Java primitive types (which may not be exact) and
BigInteger
.
In the descriptions of constructors and methods in this documentation,
the value of a BigDecimal
number object is shown as the
result of invoking the toString()
method on the object.
The internal representation of a decimal number is neither defined
nor exposed, and is not permitted to affect the result of any
operation.
The floating point arithmetic provided by this class is defined by
the ANSI X3.274-1996 standard, and is also documented at
http://www2.hursley.ibm.com/decimal
BigDecimal
numbers are controlled by a
MathContext
object, which provides the context (precision and
other information) for the operation. Methods that can take a
MathContext
parameter implement the standard arithmetic
operators for BigDecimal
objects and are known as
operator methods. The default settings provided by the
constant MathContext.DEFAULT
(digits=9,
form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP
)
perform general-purpose floating point arithmetic to nine digits of
precision. The MathContext
parameter must not be
null
.
Each operator method also has a version provided which does
not take a MathContext
parameter. For this version of
each method, the context settings used are digits=0,
form=PLAIN, lostDigits=false, roundingMode=ROUND_HALF_UP
;
these settings perform fixed point arithmetic with unlimited
precision, as defined for the original BigDecimal class in Java 1.1
and Java 1.2.
For monadic operators, only the optional MathContext
parameter is present; the operation acts upon the current object.
For dyadic operators, a BigDecimal
parameter is always
present; it must not be null
.
The operation acts with the current object being the left-hand operand
and the BigDecimal
parameter being the right-hand operand.
For example, adding two BigDecimal
objects referred to
by the names award
and extra
could be
written as any of:
award.add(extra)
award.add(extra, MathContext.DEFAULT)
award.add(extra, acontext)
(where acontext
is a MathContext
object),
which would return a BigDecimal
object whose value is
the result of adding award
and extra
under
the appropriate context settings.
When a BigDecimal
operator method is used, a set of
rules define what the result will be (and, by implication, how the
result would be represented as a character string).
These rules are defined in the BigDecimal arithmetic documentation
(see the URL above), but in summary:
MathContext
parameter for an operation
were MathContext.DEFAULT
then the result would be
rounded to 9 digits; the division of 2 by 3 would then result in
0.666666667.
MathContext
object. This lets you
calculate using as many digits as you need -- thousands, if necessary.
Fixed point (scaled) arithmetic is indicated by using a
digits
setting of 0 (or omitting the
MathContext
parameter).
form
setting
is not PLAIN
), a zero result is always expressed as the
single digit '0'
(that is, with no sign, decimal point,
or exponent part).
new BigDecimal("2.40").add( new BigDecimal("2")) => "4.40"
new BigDecimal("2.40").subtract(new BigDecimal("2")) => "0.40"
new BigDecimal("2.40").multiply(new BigDecimal("2")) => "4.80"
new BigDecimal("2.40").divide( new BigDecimal("2"), def) => "1.2"
where the value on the right of the =>
would be the
result of the operation, expressed as a String
, and
def
(in this and following examples) refers to
MathContext.DEFAULT
).
This preservation of trailing zeros is desirable for most
calculations (including financial calculations).
If necessary, trailing zeros may be easily removed using division by 1.
digits
(the default is 9 digits).
If the number of places needed before the decimal point exceeds the
digits
setting, or the absolute value of the number is
less than 0.000001
, then the number will be expressed in
exponential notation; thus
new BigDecimal("1e+6").multiply(new BigDecimal("1e+6"), def)
results in 1E+12
instead of
1000000000000
, and
new BigDecimal("1").divide(new BigDecimal("3E+10"), def)
results in 3.33333333E-11
instead of
0.0000000000333333333
.
The form of the exponential notation (scientific or engineering) is
determined by the form
setting.
java.lang.Number
, java.math.BigInteger
,
and java.math.BigDecimal
in Java 1.1 and Java 1.2.
MathContext
, Serialized FormField Summary | |
static BigDecimal |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static int |
|
static BigDecimal |
|
static BigDecimal |
|
Constructor Summary | |
| |
| |
| |
| |
| |
| |
| |
| |
|
Method Summary | |
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
byte |
|
int |
|
int |
|
int | |
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
double |
|
boolean | |
float |
|
String |
|
String |
|
int |
|
int |
|
int |
|
long |
|
long |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
int |
|
BigDecimal |
|
BigDecimal |
|
short |
|
int |
|
BigDecimal |
|
BigDecimal |
|
BigDecimal |
|
BigInteger |
|
BigInteger |
|
char[] |
|
String |
|
BigInteger |
|
static BigDecimal |
|
static BigDecimal |
|
static BigDecimal |
|
public static final int ROUND_CEILING
Rounding mode to round to a more positive number.
- Field Value:
- 2
- See Also:
MathContext.ROUND_CEILING
public static final int ROUND_DOWN
Rounding mode to round towards zero.
- Field Value:
- 1
- See Also:
MathContext.ROUND_DOWN
public static final int ROUND_FLOOR
Rounding mode to round to a more negative number.
- Field Value:
- 3
- See Also:
MathContext.ROUND_FLOOR
public static final int ROUND_HALF_DOWN
Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.
- Field Value:
- 5
- See Also:
MathContext.ROUND_HALF_DOWN
public static final int ROUND_HALF_EVEN
Rounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.
- Field Value:
- 6
- See Also:
MathContext.ROUND_HALF_EVEN
public static final int ROUND_HALF_UP
Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.
- Field Value:
- 4
- See Also:
MathContext.ROUND_HALF_UP
public static final int ROUND_UNNECESSARY
Rounding mode to assert that no rounding is necessary.
- Field Value:
- 7
- See Also:
MathContext.ROUND_UNNECESSARY
public static final int ROUND_UP
Rounding mode to round away from zero.
- Field Value:
- 0
- See Also:
MathContext.ROUND_UP
public BigDecimal(double num)
Constructs aBigDecimal
object directly from adouble
. Constructs aBigDecimal
which is the exact decimal representation of the 64-bit signed binary floating point parameter. Note that this constructor it an exact conversion; it does not give the same result as convertingnum
to aString
using theDouble.toString()
method and then using theBigDecimal(String)
constructor. To get that result, use the staticvalueOf(double)
method to construct aBigDecimal
from adouble
.
- Parameters:
num
- Thedouble
to be converted.
public BigDecimal(inchars[] )
Constructs aBigDecimal
object from an array of characters. Constructs aBigDecimal
as though aString
had been constructed from the character array and theBigDecimal(String)
constructor had then been used. The parameter must not benull
. Using this constructor is faster than using theBigDecimal(String)
constructor if the string is already available in character array form.
- Parameters:
public BigDecimal(inchars[] , int offset, int length)
Constructs aBigDecimal
object from an array of characters. Constructs aBigDecimal
as though aString
had been constructed from the character array (or a subarray of that array) and theBigDecimal(String)
constructor had then been used. The first parameter must not benull
, and the subarray must be wholly contained within it. Using this constructor is faster than using theBigDecimal(String)
constructor if the string is already available within a character array.
- Parameters:
offset
- Theint
offset into the array of the start of the number to be converted.length
- Theint
length of the number.
public BigDecimal(int num)
Constructs aBigDecimal
object directly from aint
. Constructs aBigDecimal
which is the exact decimal representation of the 32-bit signed binary integer parameter. TheBigDecimal
will contain only decimal digits, prefixed with a leading minus sign (hyphen) if the parameter is negative. A leading zero will be present only if the parameter is zero.
- Parameters:
num
- Theint
to be converted.
public BigDecimal(String string)
Constructs aBigDecimal
object from aString
. Constructs aBigDecimal
from the parameter, which must not benull
and must represent a valid number, as described formally in the documentation referred toabove
. In summary, numbers inString
form must have at least one digit, may have a leading sign, may have a decimal point, and exponential notation may be used. They follow conventional syntax, and may not contain blanks. Some valid strings from which aBigDecimal
might be constructed are:"0" -- Zero "12" -- A whole number "-76" -- A signed whole number "12.70" -- Some decimal places "+0.003" -- Plus sign is allowed "17." -- The same as 17 ".5" -- The same as 0.5 "4E+9" -- Exponential notation "0.73e-7" -- Exponential notation(Exponential notation means that the number includes an optional sign and a power of ten following an 'E' that indicates how the decimal point will be shifted. Thus the"4E+9"
above is just a short way of writing4000000000
, and the"0.73e-7"
is short for0.000000073
.) TheBigDecimal
constructed from the String is in a standard form, with no blanks, as though theadd(BigDecimal)
method had been used to add zero to the number with unlimited precision. If the string uses exponential notation (that is, includes ane
or anE
), then theBigDecimal
number will be expressed in scientific notation (where the power of ten is adjusted so there is a single non-zero digit to the left of the decimal point); in this case if the number is zero then it will be expressed as the single digit 0, and if non-zero it will have an exponent unless that exponent would be 0. The exponent must fit in nine digits both before and after it is expressed in scientific notation. Any digits in the parameter must be decimal; that is,Character.digit(c, 10)
(where c is the character in question) would not return -1.
- Parameters:
string
- TheString
to be converted.
public BigDecimal(BigDecimal bd)
Constructs aBigDecimal
object from ajava.math.BigDecimal
. Constructs aBigDecimal
as though the parameter had been represented as aString
(using itstoString
method) and theBigDecimal(String)
constructor had then been used. The parameter must not benull
. (Note: this constructor is provided only in thecom.ibm.icu.math
version of the BigDecimal class. It would not be present in ajava.math
version.)
- Parameters:
bd
- TheBigDecimal
to be translated.
public BigDecimal(BigInteger bi)
Constructs aBigDecimal
object from aBigInteger
, with scale 0. Constructs aBigDecimal
which is the exact decimal representation of theBigInteger
, with a scale of zero. The value of theBigDecimal
is identical to the value of theBigInteger
. The parameter must not benull
. TheBigDecimal
will contain only decimal digits, prefixed with a leading minus sign (hyphen) if theBigInteger
is negative. A leading zero will be present only if theBigInteger
is zero.
- Parameters:
bi
- TheBigInteger
to be converted.
public BigDecimal(BigInteger bi, int scale)
Constructs aBigDecimal
object from aBigInteger
and a scale. Constructs aBigDecimal
which is the exact decimal representation of theBigInteger
, scaled by the second parameter, which may not be negative. The value of theBigDecimal
is theBigInteger
divided by ten to the power of the scale. TheBigInteger
parameter must not benull
. TheBigDecimal
will contain only decimal digits, (with an embedded decimal point followed byscale
decimal digits if the scale is positive), prefixed with a leading minus sign (hyphen) if theBigInteger
is negative. A leading zero will be present only if theBigInteger
is zero.
- Parameters:
bi
- TheBigInteger
to be converted.scale
- Theint
specifying the scale.
public BigDecimal(long num)
Constructs aBigDecimal
object directly from along
. Constructs aBigDecimal
which is the exact decimal representation of the 64-bit signed binary integer parameter. TheBigDecimal
will contain only decimal digits, prefixed with a leading minus sign (hyphen) if the parameter is negative. A leading zero will be present only if the parameter is zero.
- Parameters:
num
- Thelong
to be converted.
public BigDecimal abs()
Returns a plainBigDecimal
whose value is the absolute value of thisBigDecimal
. The same asabs(MathContext)
, where the context isnew MathContext(0, MathContext.PLAIN)
. The length of the decimal part (the scale) of the result will bethis.scale()
- Returns:
- A
BigDecimal
whose value is the absolute value of thisBigDecimal
.
public BigDecimal abs(MathContext set)
Returns aBigDecimal
whose value is the absolute value of thisBigDecimal
. If the current object is zero or positive, then the same result as invoking theplus(MathContext)
method with the same parameter is returned. Otherwise, the same result as invoking thenegate(MathContext)
method with the same parameter is returned.
- Parameters:
set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value is the absolute value of thisBigDecimal
.
public BigDecimal add(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis+rhs
, using fixed point arithmetic. The same asadd(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
. The length of the decimal part (the scale) of the result will be the maximum of the scales of the two operands.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the addition.
- Returns:
- A
BigDecimal
whose value isthis+rhs
, using fixed point arithmetic.
public BigDecimal add(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis+rhs
. Implements the addition (+
) operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the addition.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value isthis+rhs
.
public byte byteValueExact()
Converts thisBigDecimal
to abyte
. If theBigDecimal
has a non-zero decimal part or is out of the possible range for abyte
(8-bit signed integer) result then anArithmeticException
is thrown.
- Returns:
- A
byte
equal in value tothis
.
public int compareTo(BigDecimal rhs)
Compares thisBigDecimal
to another, using unlimited precision. The same ascompareTo(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the comparison.
- Returns:
- An
int
whose value is -1, 0, or 1 asthis
is numerically less than, equal to, or greater thanrhs
.
- See Also:
compareTo(Object)
public int compareTo(BigDecimal rhs, MathContext set)
Compares thisBigDecimal
to another. Implements numeric comparison, (as defined in the decimal documentation, seeclass header
), and returns a result of typeint
. The result will be:A
-1 if the current object is less than the first parameter 0 if the current object is equal to the first parameter 1 if the current object is greater than the first parameter. compareTo(Object)
method is also provided.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the comparison.set
- TheMathContext
arithmetic settings.
- Returns:
- An
int
whose value is -1, 0, or 1 asthis
is numerically less than, equal to, or greater thanrhs
.
- See Also:
compareTo(Object)
public int compareTo(Object rhsobj)
Compares thisBigDecimal
with the value of the parameter. If the parameter isnull
, or is not an instance of theBigDecimal
type, an exception is thrown. Otherwise, the parameter is cast to typeBigDecimal
and the result of thecompareTo(BigDecimal)
method, using the cast parameter, is returned. ThecompareTo(BigDecimal,MathContext)
method should be used when aMathContext
is needed for the comparison.
- Parameters:
rhsobj
- TheObject
for the right hand side of the comparison.
- Returns:
- An
int
whose value is -1, 0, or 1 asthis
is numerically less than, equal to, or greater thanrhs
.
- See Also:
compareTo(BigDecimal)
public BigDecimal divide(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic. The same asdivide(BigDecimal,int)
, where theBigDecimal
isrhs
, and the rounding mode isMathContext.ROUND_HALF_UP
. The length of the decimal part (the scale) of the result will be the same as the scale of the current object, if the latter were formatted without exponential notation.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the division.
- Returns:
- A plain
BigDecimal
whose value isthis/rhs
, using fixed point arithmetic.
public BigDecimal divide(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis/rhs
. Implements the division (/
) operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the division.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value isthis/rhs
.
public BigDecimal divide(BigDecimal rhs, int round)
Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic and a rounding mode. The same asdivide(BigDecimal,int,int)
, where theBigDecimal
isrhs
, and the second parameter isthis.scale()
, and the third isround
. The length of the decimal part (the scale) of the result will therefore be the same as the scale of the current object, if the latter were formatted without exponential notation.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the division.round
- Theint
rounding mode to be used for the division (see theMathContext
class).
- Returns:
- A plain
BigDecimal
whose value isthis/rhs
, using fixed point arithmetic and the specified rounding mode.
public BigDecimal divide(BigDecimal rhs, int scale, int round)
Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic and a given scale and rounding mode. The same asdivide(BigDecimal,MathContext)
, where theBigDecimal
isrhs
,new MathContext(0, MathContext.PLAIN, false, round)
, except that the length of the decimal part (the scale) to be used for the result is explicit rather than being taken fromthis
. The length of the decimal part (the scale) of the result will be the same as the scale of the current object, if the latter were formatted without exponential notation.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the division.scale
- Theint
scale to be used for the result.round
- Theint
rounding mode to be used for the division (see theMathContext
class).
- Returns:
- A plain
BigDecimal
whose value isthis/rhs
, using fixed point arithmetic and the specified rounding mode.
public BigDecimal divideInteger(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the integer part ofthis/rhs
. The same asdivideInteger(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the integer division.
- Returns:
- A
BigDecimal
whose value is the integer part ofthis/rhs
.
public BigDecimal divideInteger(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the integer part ofthis/rhs
. Implements the integer division operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the integer division.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value is the integer part ofthis/rhs
.
public double doubleValue()
Converts thisBigDecimal
to adouble
. If theBigDecimal
is out of the possible range for adouble
(64-bit signed floating point) result then anArithmeticException
is thrown. The double produced is identical to result of expressing theBigDecimal
as aString
and then converting it using theDouble(String)
constructor; this can result in values ofDouble.NEGATIVE_INFINITY
orDouble.POSITIVE_INFINITY
.
- Returns:
- A
double
corresponding tothis
.
public boolean equals(Object obj)
Compares thisBigDecimal
withrhs
for equality. If the parameter isnull
, or is not an instance of the BigDecimal type, or is not exactly equal to the currentBigDecimal
object, then false is returned. Otherwise, true is returned. "Exactly equal", here, means that theString
representations of theBigDecimal
numbers are identical (they have the same characters in the same sequence). ThecompareTo(BigDecimal,MathContext)
method should be used for more general comparisons.
- Parameters:
obj
- TheObject
for the right hand side of the comparison.
- Returns:
- A
boolean
whose value true if and only if the operands have identical string representations.
- See Also:
compareTo(Object)
,compareTo(BigDecimal)
,compareTo(BigDecimal,MathContext)
public float floatValue()
Converts thisBigDecimal
to afloat
. If theBigDecimal
is out of the possible range for afloat
(32-bit signed floating point) result then anArithmeticException
is thrown. The float produced is identical to result of expressing theBigDecimal
as aString
and then converting it using theFloat(String)
constructor; this can result in values ofFloat.NEGATIVE_INFINITY
orFloat.POSITIVE_INFINITY
.
- Returns:
- A
float
corresponding tothis
.
public String format(int before, int after)
Returns theString
representation of thisBigDecimal
, modified by layout parameters. This method is provided as a primitive for use by more sophisticated classes, such asDecimalFormat
, that can apply locale-sensitive editing of the result. The level of formatting that it provides is a necessary part of the BigDecimal class as it is sensitive to and must follow the calculation and rounding rules for BigDecimal arithmetic. However, if the function is provided elsewhere, it may be removed from this class. The parameters, for both forms of theformat
method are all of typeint
. A value of -1 for any parameter indicates that the default action or value for that parameter should be used. The parameters,before
andafter
, specify the number of characters to be used for the integer part and decimal part of the result respectively. Exponential notation is not used. If either parameter is -1 (which indicates the default action), the number of characters used will be exactly as many as are needed for that part.before
must be a positive number; if it is larger than is needed to contain the integer part, that part is padded on the left with blanks to the requested length. Ifbefore
is not large enough to contain the integer part of the number (including the sign, for negative numbers) an exception is thrown.after
must be a non-negative number; if it is not the same size as the decimal part of the number, the number will be rounded (or extended with zeros) to fit. Specifying 0 forafter
will cause the number to be rounded to an integer (that is, it will have no decimal part or decimal point). The rounding method will be the default,MathContext.ROUND_HALF_UP
. Other rounding methods, and the use of exponential notation, can be selected by usingformat(int,int,int,int,int,int)
. Using the two-parameter form of the method has exactly the same effect as using the six-parameter form with the final four parameters all being -1.
- Parameters:
before
- Theint
specifying the number of places before the decimal point. Use -1 for 'as many as are needed'.after
- Theint
specifying the number of places after the decimal point. Use -1 for 'as many as are needed'.
- Returns:
- A
String
representing thisBigDecimal
, laid out according to the specified parameters
- See Also:
toString()
,toCharArray()
public String format(int before, int after, int explaces, int exdigits, int exformint, int exround)
Returns theString
representation of thisBigDecimal
, modified by layout parameters and allowing exponential notation. This method is provided as a primitive for use by more sophisticated classes, such asDecimalFormat
, that can apply locale-sensitive editing of the result. The level of formatting that it provides is a necessary part of the BigDecimal class as it is sensitive to and must follow the calculation and rounding rules for BigDecimal arithmetic. However, if the function is provided elsewhere, it may be removed from this class. The parameters are all of typeint
. A value of -1 for any parameter indicates that the default action or value for that parameter should be used. The first two parameters (before
andafter
) specify the number of characters to be used for the integer part and decimal part of the result respectively, as defined forformat(int,int)
. If either of these is -1 (which indicates the default action), the number of characters used will be exactly as many as are needed for that part. The remaining parameters control the use of exponential notation and rounding. Three (explaces
,exdigits
, andexform
) control the exponent part of the result. As before, the default action for any of these parameters may be selected by using the value -1.explaces
must be a positive number; it sets the number of places (digits after the sign of the exponent) to be used for any exponent part, the default (whenexplaces
is -1) being to use as many as are needed. Ifexplaces
is not -1, space is always reserved for an exponent; if one is not needed (for example, if the exponent will be 0) thenexplaces
+2 blanks are appended to the result. <!-- (This preserves vertical alignment of similarly formatted numbers in a monospace font.) --> Ifexplaces
is not -1 and is not large enough to contain the exponent, an exception is thrown.exdigits
sets the trigger point for use of exponential notation. If, before any rounding, the number of places needed before the decimal point exceedsexdigits
, or if the absolute value of the result is less than0.000001
, then exponential form will be used, provided thatexdigits
was specified. Whenexdigits
is -1, exponential notation will never be used. If 0 is specified forexdigits
, exponential notation is always used unless the exponent would be 0.exform
sets the form for exponential notation (if needed). It may be eitherMathContext.SCIENTIFIC
orMathContext.ENGINEERING
. If the latter, engineering, form is requested, up to three digits (plus sign, if negative) may be needed for the integer part of the result (before
). Otherwise, only one digit (plus sign, if negative) is needed. Finally, the sixth argument,exround
, selects the rounding algorithm to be used, and must be one of the values indicated by a public constant in theMathContext
class whose name starts withROUND_
. The default (ROUND_HALF_UP
) may also be selected by using the value -1, as before. The special valueMathContext.ROUND_UNNECESSARY
may be used to detect whether non-zero digits are discarded -- ifexround
has this value than if non-zero digits would be discarded (rounded) during formatting then anArithmeticException
is thrown.
- Parameters:
before
- Theint
specifying the number of places before the decimal point. Use -1 for 'as many as are needed'.after
- Theint
specifying the number of places after the decimal point. Use -1 for 'as many as are needed'.explaces
- Theint
specifying the number of places to be used for any exponent. Use -1 for 'as many as are needed'.exdigits
- Theint
specifying the trigger (digits before the decimal point) which if exceeded causes exponential notation to be used. Use 0 to force exponential notation. Use -1 to force plain notation (no exponential notation).exformint
- Theint
specifying the form of exponential notation to be used (MathContext.SCIENTIFIC
orMathContext.ENGINEERING
).exround
- Theint
specifying the rounding mode to use. Use -1 for the default,MathContext.ROUND_HALF_UP
.
- Returns:
- A
String
representing thisBigDecimal
, laid out according to the specified parameters
- See Also:
toString()
,toCharArray()
public int hashCode()
Returns the hashcode for thisBigDecimal
. This hashcode is suitable for use by thejava.util.Hashtable
class. Note that twoBigDecimal
objects are only guaranteed to produce the same hashcode if they are exactly equal (that is, theString
representations of theBigDecimal
numbers are identical -- they have the same characters in the same sequence).
- Returns:
- An
int
that is the hashcode forthis
.
public int intValue()
Converts thisBigDecimal
to anint
. If theBigDecimal
has a non-zero decimal part it is discarded. If theBigDecimal
is out of the possible range for anint
(32-bit signed integer) result then only the low-order 32 bits are used. (That is, the number may be decapitated.) To avoid unexpected errors when these conditions occur, use theintValueExact()
method.
- Returns:
- An
int
converted fromthis
, truncated and decapitated if necessary.
public int intValueExact()
Converts thisBigDecimal
to anint
. If theBigDecimal
has a non-zero decimal part or is out of the possible range for anint
(32-bit signed integer) result then anArithmeticException
is thrown.
- Returns:
- An
int
equal in value tothis
.
public long longValue()
Converts thisBigDecimal
to along
. If theBigDecimal
has a non-zero decimal part it is discarded. If theBigDecimal
is out of the possible range for along
(64-bit signed integer) result then only the low-order 64 bits are used. (That is, the number may be decapitated.) To avoid unexpected errors when these conditions occur, use thelongValueExact()
method.
- Returns:
- A
long
converted fromthis
, truncated and decapitated if necessary.
public long longValueExact()
Converts thisBigDecimal
to along
. If theBigDecimal
has a non-zero decimal part or is out of the possible range for along
(64-bit signed integer) result then anArithmeticException
is thrown.
- Returns:
- A
long
equal in value tothis
.
public BigDecimal max(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the maximum ofthis
andrhs
. The same asmax(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the comparison.
- Returns:
- A
BigDecimal
whose value is the maximum ofthis
andrhs
.
public BigDecimal max(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the maximum ofthis
andrhs
. Returns the larger of the current object and the first parameter. If calling thecompareTo(BigDecimal,MathContext)
method with the same parameters would return1
or0
, then the result of calling theplus(MathContext)
method on the current object (using the sameMathContext
parameter) is returned. Otherwise, the result of calling theplus(MathContext)
method on the first parameter object (using the sameMathContext
parameter) is returned.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the comparison.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value is the maximum ofthis
andrhs
.
public BigDecimal min(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the minimum ofthis
andrhs
. The same asmin(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the comparison.
- Returns:
- A
BigDecimal
whose value is the minimum ofthis
andrhs
.
public BigDecimal min(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the minimum ofthis
andrhs
. Returns the smaller of the current object and the first parameter. If calling thecompareTo(BigDecimal,MathContext)
method with the same parameters would return-1
or0
, then the result of calling theplus(MathContext)
method on the current object (using the sameMathContext
parameter) is returned. Otherwise, the result of calling theplus(MathContext)
method on the first parameter object (using the sameMathContext
parameter) is returned.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the comparison.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value is the minimum ofthis
andrhs
.
public BigDecimal movePointLeft(int n)
Returns a plainBigDecimal
whose decimal point has been moved to the left by a specified number of positions. The parameter,n
, specifies the number of positions to move the decimal point. That is, ifn
is 0 or positive, the number returned is given by:this.multiply(TEN.pow(new BigDecimal(-n)))
n
may be negative, in which case the method returns the same result asmovePointRight(-n)
.
- Parameters:
n
- Theint
specifying the number of places to move the decimal point leftwards.
- Returns:
- A
BigDecimal
derived fromthis
, with the decimal point movedn
places to the left.
public BigDecimal movePointRight(int n)
Returns a plainBigDecimal
whose decimal point has been moved to the right by a specified number of positions. The parameter,n
, specifies the number of positions to move the decimal point. That is, ifn
is 0 or positive, the number returned is given by:this.multiply(TEN.pow(new BigDecimal(n)))
n
may be negative, in which case the method returns the same result asmovePointLeft(-n)
.
- Parameters:
n
- Theint
specifying the number of places to move the decimal point rightwards.
- Returns:
- A
BigDecimal
derived fromthis
, with the decimal point movedn
places to the right.
public BigDecimal multiply(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis*rhs
, using fixed point arithmetic. The same asadd(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
. The length of the decimal part (the scale) of the result will be the sum of the scales of the operands, if they were formatted without exponential notation.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the multiplication.
- Returns:
- A
BigDecimal
whose value isthis*rhs
, using fixed point arithmetic.
public BigDecimal multiply(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis*rhs
. Implements the multiplication (*
) operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the multiplication.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value isthis*rhs
.
public BigDecimal negate()
Returns a plainBigDecimal
whose value is-this
. The same asnegate(MathContext)
, where the context isnew MathContext(0, MathContext.PLAIN)
. The length of the decimal part (the scale) of the result will be bethis.scale()
- Returns:
- A
BigDecimal
whose value is-this
.
public BigDecimal negate(MathContext set)
Returns aBigDecimal
whose value is-this
. Implements the negation (Prefix-
) operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object.
- Parameters:
set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value is-this
.
public BigDecimal plus()
Returns a plainBigDecimal
whose value is+this
. Note thatthis
is not necessarily a plainBigDecimal
, but the result will always be. The same asplus(MathContext)
, where the context isnew MathContext(0, MathContext.PLAIN)
. The length of the decimal part (the scale) of the result will be bethis.scale()
- Returns:
- A
BigDecimal
whose value is+this
.
public BigDecimal plus(MathContext set)
Returns aBigDecimal
whose value is+this
. Implements the plus (Prefix+
) operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object. This method is useful for rounding or otherwise applying a context to a decimal value.
- Parameters:
set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value is+this
.
public BigDecimal pow(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis**rhs
, using fixed point arithmetic. The same aspow(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
. The parameter is the power to which thethis
will be raised; it must be in the range 0 through 999999999, and must have a decimal part of zero. Note that these restrictions may be removed in the future, so they should not be used as a test for a whole number. In addition, the power must not be negative, as noMathContext
is used and so the result would then always be 0.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the operation (the power).
- Returns:
- A
BigDecimal
whose value isthis**rhs
, using fixed point arithmetic.
public BigDecimal pow(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis**rhs
. Implements the power (**
) operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object. The first parameter is the power to which thethis
will be raised; it must be in the range -999999999 through 999999999, and must have a decimal part of zero. Note that these restrictions may be removed in the future, so they should not be used as a test for a whole number. If thedigits
setting of theMathContext
parameter is 0, the power must be zero or positive.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the operation (the power).set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value isthis**rhs
.
public BigDecimal remainder(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the remainder ofthis/rhs
, using fixed point arithmetic. The same asremainder(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
. This is not the modulo operator -- the result may be negative.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the remainder operation.
- Returns:
- A
BigDecimal
whose value is the remainder ofthis/rhs
, using fixed point arithmetic.
public BigDecimal remainder(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the remainder ofthis/rhs
. Implements the remainder operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object. This is not the modulo operator -- the result may be negative.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the remainder operation.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value is the remainder ofthis+rhs
.
public int scale()
Returns the scale of thisBigDecimal
. Returns a non-negativeint
which is the scale of the number. The scale is the number of digits in the decimal part of the number if the number were formatted without exponential notation.
- Returns:
- An
int
whose value is the scale of thisBigDecimal
.
public BigDecimal setScale(int scale)
Returns a plainBigDecimal
with a given scale. If the given scale (which must be zero or positive) is the same as or greater than the length of the decimal part (the scale) of thisBigDecimal
then trailing zeros will be added to the decimal part as necessary. If the given scale is less than the length of the decimal part (the scale) of thisBigDecimal
then trailing digits will be removed, and in this case anArithmeticException
is thrown if any discarded digits are non-zero. The same assetScale(int,int)
, where the first parameter is the scale, and the second isMathContext.ROUND_UNNECESSARY
.
- Parameters:
scale
- Theint
specifying the scale of the resultingBigDecimal
.
- Returns:
- A plain
BigDecimal
with the given scale.
public BigDecimal setScale(int scale, int round)
Returns a plainBigDecimal
with a given scale. If the given scale (which must be zero or positive) is the same as or greater than the length of the decimal part (the scale) of thisBigDecimal
then trailing zeros will be added to the decimal part as necessary. If the given scale is less than the length of the decimal part (the scale) of thisBigDecimal
then trailing digits will be removed, and the rounding mode given by the second parameter is used to determine if the remaining digits are affected by a carry. In this case, anIllegalArgumentException
is thrown ifround
is not a valid rounding mode. Ifround
isMathContext.ROUND_UNNECESSARY
, anArithmeticException
is thrown if any discarded digits are non-zero.
- Parameters:
scale
- Theint
specifying the scale of the resultingBigDecimal
.round
- Theint
rounding mode to be used for the division (see theMathContext
class).
- Returns:
- A plain
BigDecimal
with the given scale.
public short shortValueExact()
Converts thisBigDecimal
to ashort
. If theBigDecimal
has a non-zero decimal part or is out of the possible range for ashort
(16-bit signed integer) result then anArithmeticException
is thrown.
- Returns:
- A
short
equal in value tothis
.
public int signum()
Returns the sign of thisBigDecimal
, as anint
. This returns the signum function value that represents the sign of thisBigDecimal
. That is, -1 if theBigDecimal
is negative, 0 if it is numerically equal to zero, or 1 if it is positive.
- Returns:
- An
int
which is -1 if theBigDecimal
is negative, 0 if it is numerically equal to zero, or 1 if it is positive.
public BigDecimal subtract(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis-rhs
, using fixed point arithmetic. The same assubtract(BigDecimal,MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
. The length of the decimal part (the scale) of the result will be the maximum of the scales of the two operands.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the subtraction.
- Returns:
- A
BigDecimal
whose value isthis-rhs
, using fixed point arithmetic.
public BigDecimal subtract(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis-rhs
. Implements the subtraction (-
) operator (as defined in the decimal documentation, seeclass header
), and returns the result as aBigDecimal
object.
- Parameters:
rhs
- TheBigDecimal
for the right hand side of the subtraction.set
- TheMathContext
arithmetic settings.
- Returns:
- A
BigDecimal
whose value isthis-rhs
.
public BigDecimal toBigDecimal()
Converts thisBigDecimal
to ajava.math.BigDecimal
. This is an exact conversion; the result is the same as if theBigDecimal
were formatted as a plain number without any rounding or exponent and then thejava.math.BigDecimal(java.lang.String)
constructor were used to construct the result. (Note: this method is provided only in thecom.ibm.icu.math
version of the BigDecimal class. It would not be present in ajava.math
version.)
- Returns:
- The
java.math.BigDecimal
equal in value to thisBigDecimal
.
public BigInteger toBigInteger()
Converts thisBigDecimal
to ajava.math.BigInteger
. Any decimal part is truncated (discarded). If an exception is desired should the decimal part be non-zero, usetoBigIntegerExact()
.
- Returns:
- The
java.math.BigInteger
equal in value to the integer part of thisBigDecimal
.
public BigInteger toBigIntegerExact()
Converts thisBigDecimal
to ajava.math.BigInteger
. An exception is thrown if the decimal part (if any) is non-zero.
- Returns:
- The
java.math.BigInteger
equal in value to the integer part of thisBigDecimal
.
public char[] toCharArray()
Returns theBigDecimal
as a character array. The result of this method is the same as using the sequencetoString().toCharArray()
, but avoids creating the intermediateString
andchar[]
objects.
- Returns:
- The
char[]
array corresponding to thisBigDecimal
.
public String toString()
Returns theBigDecimal
as aString
. This returns aString
that exactly represents thisBigDecimal
, as defined in the decimal documentation (seeclass header
). By definition, using theBigDecimal(String)
constructor on the resultString
will create aBigDecimal
that is exactly equal to the originalBigDecimal
.
- Returns:
- The
String
exactly corresponding to thisBigDecimal
.
public BigInteger unscaledValue()
Returns the number as aBigInteger
after removing the scale. That is, the number is expressed as a plain number, any decimal point is then removed (retaining the digits of any decimal part), and the result is then converted to aBigInteger
.
- Returns:
- The
java.math.BigInteger
equal in value to thisBigDecimal
multiplied by ten to the power ofthis.scale()
.
public static BigDecimal valueOf(double dub)
Translates adouble
to aBigDecimal
. Returns aBigDecimal
which is the decimal representation of the 64-bit signed binary floating point parameter. If the parameter is infinite, or is not a number (NaN), aNumberFormatException
is thrown. The number is constructed as thoughnum
had been converted to aString
using theDouble.toString()
method and theBigDecimal(String)
constructor had then been used. This is typically not an exact conversion.
- Parameters:
dub
- Thedouble
to be translated.
- Returns:
- The
BigDecimal
equal in value todub
.
public static BigDecimal valueOf(long lint)
Translates along
to aBigDecimal
. That is, returns a plainBigDecimal
whose value is equal to the givenlong
.
- Parameters:
lint
- Thelong
to be translated.
- Returns:
- The
BigDecimal
equal in value tolint
.
public static BigDecimal valueOf(long lint, int scale)
Translates along
to aBigDecimal
with a given scale. That is, returns a plainBigDecimal
whose unscaled value is equal to the givenlong
, adjusted by the second parameter,scale
. The result is given by:(new BigDecimal(lint)).divide(TEN.pow(new BigDecimal(scale)))
ANumberFormatException
is thrown ifscale
is negative.
- Parameters:
lint
- Thelong
to be translated.scale
- Theint
scale to be applied.
- Returns:
- The
BigDecimal
equal in value tolint
.