Class BigDecimal
- java.lang.Object
-
- java.lang.Number
-
- com.ibm.icu.math.BigDecimal
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Comparable<BigDecimal>
public class BigDecimal extends java.lang.Number implements java.io.Serializable, java.lang.Comparable<BigDecimal>
TheBigDecimal
class implements immutable arbitrary-precision decimal numbers. The methods of theBigDecimal
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 itsString
representation; theBigDecimal
class provides direct conversions to and fromString
and character array (char[]
) objects, as well as conversions to and from the Java primitive types (which may not be exact) andBigInteger
.In the descriptions of constructors and methods in this documentation, the value of a
BigDecimal
number object is shown as the result of invoking thetoString()
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
[This URL will change.]Operator methods
Operations on
BigDecimal
numbers are controlled by aMathContext
object, which provides the context (precision and other information) for the operation. Methods that can take aMathContext
parameter implement the standard arithmetic operators forBigDecimal
objects and are known as operator methods. The default settings provided by the constantMathContext.DEFAULT
(digits=9, form=SCIENTIFIC, lostDigits=false, roundingMode=ROUND_HALF_UP
) perform general-purpose floating point arithmetic to nine digits of precision. TheMathContext
parameter must not benull
.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 aredigits=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 benull
. The operation acts with the current object being the left-hand operand and theBigDecimal
parameter being the right-hand operand.For example, adding two
BigDecimal
objects referred to by the namesaward
andextra
could be written as any of:award.add(extra)
award.add(extra, MathContext.DEFAULT)
award.add(extra, acontext)(where
acontext
is aMathContext
object), which would return aBigDecimal
object whose value is the result of addingaward
andextra
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:- Results are normally calculated with up to some maximum number of significant digits. For example, if the
MathContext
parameter for an operation wereMathContext.DEFAULT
then the result would be rounded to 9 digits; the division of 2 by 3 would then result in 0.666666667.
You can change the default of 9 significant digits by providing the method with a suitableMathContext
object. This lets you calculate using as many digits as you need -- thousands, if necessary. Fixed point (scaled) arithmetic is indicated by using adigits
setting of 0 (or omitting theMathContext
parameter).
Similarly, you can change the algorithm used for rounding from the default "classic" algorithm. -
In standard arithmetic (that is, when the
form
setting is notPLAIN
), a zero result is always expressed as the single digit'0'
(that is, with no sign, decimal point, or exponent part). -
Except for the division and power operators in standard arithmetic, trailing zeros are preserved (this is in contrast
to binary floating point operations and most electronic calculators, which lose the information about trailing zeros
in the fractional part of results).
So, for example: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 aString
, anddef
(in this and following examples) refers toMathContext.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. -
In standard arithmetic, exponential form is used for a result depending on its value and the current setting of
digits
(the default is 9 digits). If the number of places needed before the decimal point exceeds thedigits
setting, or the absolute value of the number is less than0.000001
, then the number will be expressed in exponential notation; thusnew BigDecimal("1e+6").multiply(new BigDecimal("1e+6"), def)
results in
1E+12
instead of1000000000000
, andnew BigDecimal("1").divide(new BigDecimal("3E+10"), def)
results in
3.33333333E-11
instead of0.0000000000333333333
.The form of the exponential notation (scientific or engineering) is determined by the
form
setting.
The names of methods in this class follow the conventions established by
java.lang.Number
,java.math.BigInteger
, andjava.math.BigDecimal
in Java 1.1 and Java 1.2.- See Also:
MathContext
, Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description private static byte[]
bytecar
private static byte[]
bytedig
private int
exp
The exponent.private byte
form
The formatting style.private byte
ind
The indicator.private static byte
isneg
private static byte
ispos
private static byte
iszero
private byte[]
mant
The value of the mantissa.private static int
MaxArg
private static int
MaxExp
private static int
MinArg
private static int
MinExp
static BigDecimal
ONE
TheBigDecimal
constant "1".private static MathContext
plainMC
static int
ROUND_CEILING
Rounding mode to round to a more positive number.static int
ROUND_DOWN
Rounding mode to round towards zero.static int
ROUND_FLOOR
Rounding mode to round to a more negative number.static int
ROUND_HALF_DOWN
Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.static int
ROUND_HALF_EVEN
Rounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.static int
ROUND_HALF_UP
Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.static int
ROUND_UNNECESSARY
Rounding mode to assert that no rounding is necessary.static int
ROUND_UP
Rounding mode to round away from zero.private static long
serialVersionUID
static BigDecimal
TEN
TheBigDecimal
constant "10".static BigDecimal
ZERO
TheBigDecimal
constant "0".
-
Constructor Summary
Constructors Modifier Constructor Description private
BigDecimal()
BigDecimal(char[] inchars)
Constructs aBigDecimal
object from an array of characters.BigDecimal(char[] inchars, int offset, int length)
Constructs aBigDecimal
object from an array of characters.BigDecimal(double num)
Constructs aBigDecimal
object directly from adouble
.BigDecimal(int num)
Constructs aBigDecimal
object directly from aint
.BigDecimal(long num)
Constructs aBigDecimal
object directly from along
.BigDecimal(java.lang.String string)
Constructs aBigDecimal
object from aString
.BigDecimal(java.math.BigDecimal bd)
Constructs aBigDecimal
object from ajava.math.BigDecimal
.BigDecimal(java.math.BigInteger bi)
Constructs aBigDecimal
object from aBigInteger
, with scale 0.BigDecimal(java.math.BigInteger bi, int scale)
Constructs aBigDecimal
object from aBigInteger
and a scale.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description BigDecimal
abs()
Returns a plainBigDecimal
whose value is the absolute value of thisBigDecimal
.BigDecimal
abs(MathContext set)
Returns aBigDecimal
whose value is the absolute value of thisBigDecimal
.BigDecimal
add(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis+rhs
, using fixed point arithmetic.BigDecimal
add(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis+rhs
.private static boolean
allzero(byte[] array, int start)
private void
bad(char[] s)
private void
badarg(java.lang.String name, int pos, java.lang.String value)
private static byte[]
byteaddsub(byte[] a, int avlen, byte[] b, int bvlen, int m, boolean reuse)
byte
byteValueExact()
Converts thisBigDecimal
to abyte
.private void
checkdigits(BigDecimal rhs, int dig)
private static BigDecimal
clone(BigDecimal dec)
int
compareTo(BigDecimal rhs)
Compares thisBigDecimal
to another, using unlimited precision.int
compareTo(BigDecimal rhs, MathContext set)
Compares thisBigDecimal
to another.private static byte[]
diginit()
BigDecimal
divide(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic.BigDecimal
divide(BigDecimal rhs, int round)
Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic and a rounding mode.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.BigDecimal
divide(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis/rhs
.BigDecimal
divideInteger(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the integer part ofthis/rhs
.BigDecimal
divideInteger(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the integer part ofthis/rhs
.private BigDecimal
dodivide(char code, BigDecimal rhs, MathContext set, int scale)
double
doubleValue()
Converts thisBigDecimal
to adouble
.boolean
equals(java.lang.Object obj)
Compares thisBigDecimal
withrhs
for equality.private static byte[]
extend(byte[] inarr, int newlen)
private BigDecimal
finish(MathContext set, boolean strip)
float
floatValue()
Converts thisBigDecimal
to afloat
.java.lang.String
format(int before, int after)
Returns theString
representation of thisBigDecimal
, modified by layout parameters.java.lang.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.int
hashCode()
Returns the hashcode for thisBigDecimal
.private int
intcheck(int min, int max)
int
intValue()
Converts thisBigDecimal
to anint
.int
intValueExact()
Converts thisBigDecimal
to anint
.private char[]
layout()
long
longValue()
Converts thisBigDecimal
to along
.long
longValueExact()
Converts thisBigDecimal
to along
.BigDecimal
max(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the maximum ofthis
andrhs
.BigDecimal
max(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the maximum ofthis
andrhs
.BigDecimal
min(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the minimum ofthis
andrhs
.BigDecimal
min(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the minimum ofthis
andrhs
.BigDecimal
movePointLeft(int n)
Returns a plainBigDecimal
whose decimal point has been moved to the left by a specified number of positions.BigDecimal
movePointRight(int n)
Returns a plainBigDecimal
whose decimal point has been moved to the right by a specified number of positions.BigDecimal
multiply(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis*rhs
, using fixed point arithmetic.BigDecimal
multiply(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis*rhs
.BigDecimal
negate()
Returns a plainBigDecimal
whose value is-this
.BigDecimal
negate(MathContext set)
Returns aBigDecimal
whose value is-this
.BigDecimal
plus()
Returns a plainBigDecimal
whose value is+this
.BigDecimal
plus(MathContext set)
Returns aBigDecimal
whose value is+this
.BigDecimal
pow(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis**rhs
, using fixed point arithmetic.BigDecimal
pow(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis**rhs
.BigDecimal
remainder(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the remainder ofthis/rhs
, using fixed point arithmetic.BigDecimal
remainder(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value is the remainder ofthis/rhs
.private BigDecimal
round(int len, int mode)
private BigDecimal
round(MathContext set)
int
scale()
Returns the scale of thisBigDecimal
.BigDecimal
setScale(int scale)
Returns a plainBigDecimal
with a given scale.BigDecimal
setScale(int scale, int round)
Returns a plainBigDecimal
with a given scale.short
shortValueExact()
Converts thisBigDecimal
to ashort
.int
signum()
Returns the sign of thisBigDecimal
, as anint
.BigDecimal
subtract(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis-rhs
, using fixed point arithmetic.BigDecimal
subtract(BigDecimal rhs, MathContext set)
Returns aBigDecimal
whose value isthis-rhs
.java.math.BigDecimal
toBigDecimal()
Converts thisBigDecimal
to ajava.math.BigDecimal
.java.math.BigInteger
toBigInteger()
Converts thisBigDecimal
to ajava.math.BigInteger
.java.math.BigInteger
toBigIntegerExact()
Converts thisBigDecimal
to ajava.math.BigInteger
.char[]
toCharArray()
Returns theBigDecimal
as a character array.java.lang.String
toString()
Returns theBigDecimal
as aString
.java.math.BigInteger
unscaledValue()
Returns the number as aBigInteger
after removing the scale.static BigDecimal
valueOf(double dub)
Translates adouble
to aBigDecimal
.static BigDecimal
valueOf(long lint)
Translates along
to aBigDecimal
.static BigDecimal
valueOf(long lint, int scale)
Translates along
to aBigDecimal
with a given scale.
-
-
-
Field Detail
-
ZERO
public static final BigDecimal ZERO
TheBigDecimal
constant "0".
-
ONE
public static final BigDecimal ONE
TheBigDecimal
constant "1".
-
TEN
public static final BigDecimal TEN
TheBigDecimal
constant "10".
-
ROUND_CEILING
public static final int ROUND_CEILING
Rounding mode to round to a more positive number.- See Also:
MathContext.ROUND_CEILING
, Constant Field Values
-
ROUND_DOWN
public static final int ROUND_DOWN
Rounding mode to round towards zero.- See Also:
MathContext.ROUND_DOWN
, Constant Field Values
-
ROUND_FLOOR
public static final int ROUND_FLOOR
Rounding mode to round to a more negative number.- See Also:
MathContext.ROUND_FLOOR
, Constant Field Values
-
ROUND_HALF_DOWN
public static final int ROUND_HALF_DOWN
Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.- See Also:
MathContext.ROUND_HALF_DOWN
, Constant Field Values
-
ROUND_HALF_EVEN
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.- See Also:
MathContext.ROUND_HALF_EVEN
, Constant Field Values
-
ROUND_HALF_UP
public static final int ROUND_HALF_UP
Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.- See Also:
MathContext.ROUND_HALF_UP
, Constant Field Values
-
ROUND_UNNECESSARY
public static final int ROUND_UNNECESSARY
Rounding mode to assert that no rounding is necessary.
-
ROUND_UP
public static final int ROUND_UP
Rounding mode to round away from zero.- See Also:
MathContext.ROUND_UP
, Constant Field Values
-
ispos
private static final byte ispos
- See Also:
- Constant Field Values
-
iszero
private static final byte iszero
- See Also:
- Constant Field Values
-
isneg
private static final byte isneg
- See Also:
- Constant Field Values
-
MinExp
private static final int MinExp
- See Also:
- Constant Field Values
-
MaxExp
private static final int MaxExp
- See Also:
- Constant Field Values
-
MinArg
private static final int MinArg
- See Also:
- Constant Field Values
-
MaxArg
private static final int MaxArg
- See Also:
- Constant Field Values
-
plainMC
private static final MathContext plainMC
-
serialVersionUID
private static final long serialVersionUID
- See Also:
- Constant Field Values
-
bytecar
private static byte[] bytecar
-
bytedig
private static byte[] bytedig
-
ind
private byte ind
The indicator. This may take the values:- ispos -- the number is positive
- iszero -- the number is zero
- isneg -- the number is negative
-
form
private byte form
The formatting style. This may take the values:- MathContext.PLAIN -- no exponent needed
- MathContext.SCIENTIFIC -- scientific notation required
- MathContext.ENGINEERING -- engineering notation required
This property is an optimization; it allows us to defer number layout until it is actually needed as a string, hence avoiding unnecessary formatting.
-
mant
private byte[] mant
The value of the mantissa.Once constructed, this may become shared between several BigDecimal objects, so must not be altered.
For efficiency (speed), this is a byte array, with each byte taking a value of 0 -> 9.
If the first byte is 0 then the value of the number is zero (and mant.length=1, except when constructed from a plain number, for example, 0.000).
-
exp
private int exp
The exponent.For fixed point arithmetic, scale is
-exp
, and can apply to zero. Note that this property can have a value less than MinExp when the mantissa has more than one digit.
-
-
Constructor Detail
-
BigDecimal
public BigDecimal(java.math.BigDecimal bd)
Constructs aBigDecimal
object from ajava.math.BigDecimal
.Constructs a
BigDecimal
as though the parameter had been represented as aString
(using itstoString
method) and theBigDecimal(java.lang.String)
constructor had then been used. The parameter must not benull
.(Note: this constructor is provided only in the
com.ibm.icu.math
version of the BigDecimal class. It would not be present in ajava.math
version.)- Parameters:
bd
- TheBigDecimal
to be translated.
-
BigDecimal
public BigDecimal(java.math.BigInteger bi)
Constructs aBigDecimal
object from aBigInteger
, with scale 0.Constructs a
BigDecimal
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
.The
BigDecimal
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.
-
BigDecimal
public BigDecimal(java.math.BigInteger bi, int scale)
Constructs aBigDecimal
object from aBigInteger
and a scale.Constructs a
BigDecimal
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
.The
BigDecimal
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.- Throws:
java.lang.NumberFormatException
- If the scale is negative.
-
BigDecimal
public BigDecimal(char[] inchars)
Constructs aBigDecimal
object from an array of characters.Constructs a
BigDecimal
as though aString
had been constructed from the character array and theBigDecimal(java.lang.String)
constructor had then been used. The parameter must not benull
.Using this constructor is faster than using the
BigDecimal(String)
constructor if the string is already available in character array form.- Parameters:
inchars
- Thechar[]
array containing the number to be converted.- Throws:
java.lang.NumberFormatException
- If the parameter is not a valid number.
-
BigDecimal
public BigDecimal(char[] inchars, int offset, int length)
Constructs aBigDecimal
object from an array of characters.Constructs a
BigDecimal
as though aString
had been constructed from the character array (or a subarray of that array) and theBigDecimal(java.lang.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 the
BigDecimal(String)
constructor if the string is already available within a character array.- Parameters:
inchars
- Thechar[]
array containing the number to be converted.offset
- Theint
offset into the array of the start of the number to be converted.length
- Theint
length of the number.- Throws:
java.lang.NumberFormatException
- If the parameter is not a valid number for any reason.
-
BigDecimal
public BigDecimal(double num)
Constructs aBigDecimal
object directly from adouble
.Constructs a
BigDecimal
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 converting
num
to aString
using theDouble.toString()
method and then using theBigDecimal(java.lang.String)
constructor. To get that result, use the staticvalueOf(double)
method to construct aBigDecimal
from adouble
.- Parameters:
num
- Thedouble
to be converted.- Throws:
java.lang.NumberFormatException
- If the parameter is infinite or not a number.
-
BigDecimal
public BigDecimal(int num)
Constructs aBigDecimal
object directly from aint
.Constructs a
BigDecimal
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.
-
BigDecimal
public BigDecimal(long num)
Constructs aBigDecimal
object directly from along
.Constructs a
BigDecimal
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.
-
BigDecimal
public BigDecimal(java.lang.String string)
Constructs aBigDecimal
object from aString
.Constructs a
BigDecimal
from the parameter, which must not benull
and must represent a valid number, as described formally in the documentation referred toabove
.In summary, numbers in
String
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 a
BigDecimal
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
.)The
BigDecimal
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)
(wherec
is the character in question) would not return -1.- Parameters:
string
- TheString
to be converted.- Throws:
java.lang.NumberFormatException
- If the parameter is not a valid number.
-
BigDecimal
private BigDecimal()
-
-
Method Detail
-
abs
public BigDecimal abs()
Returns a plainBigDecimal
whose value is the absolute value of thisBigDecimal
.The same as
abs(MathContext)
, where the context isnew MathContext(0, MathContext.PLAIN)
.The length of the decimal part (the scale) of the result will be
this.scale()
- Returns:
- A
BigDecimal
whose value is the absolute value of thisBigDecimal
.
-
abs
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 the
plus(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
.
-
add
public BigDecimal add(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis+rhs
, using fixed point arithmetic.The same as
add(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.
-
add
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
.
-
compareTo
public int compareTo(BigDecimal rhs)
Compares thisBigDecimal
to another, using unlimited precision.The same as
compareTo(BigDecimal, MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
.- Specified by:
compareTo
in interfacejava.lang.Comparable<BigDecimal>
- 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
.
-
compareTo
public int compareTo(BigDecimal rhs, MathContext set)
Compares thisBigDecimal
to another.Implements numeric comparison, (as defined in the decimal documentation, see
class header
), and returns a result of typeint
.The result will be:
-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. A
compareTo(BigDecimal)
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
.
-
divide
public BigDecimal divide(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic.The same as
divide(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. - Throws:
java.lang.ArithmeticException
- Ifrhs
is zero.
-
divide
public BigDecimal divide(BigDecimal rhs, int round)
Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic and a rounding mode.The same as
divide(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. - Throws:
java.lang.IllegalArgumentException
- ifround
is not a valid rounding mode.java.lang.ArithmeticException
- ifrhs
is zero.java.lang.ArithmeticException
- ifround
isMathContext.ROUND_UNNECESSARY
andthis.scale()
is insufficient to represent the result exactly.
-
divide
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 as
divide(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. - Throws:
java.lang.IllegalArgumentException
- ifround
is not a valid rounding mode.java.lang.ArithmeticException
- ifrhs
is zero.java.lang.ArithmeticException
- ifscale
is negative.java.lang.ArithmeticException
- ifround
isMathContext.ROUND_UNNECESSARY
andscale
is insufficient to represent the result exactly.
-
divide
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
. - Throws:
java.lang.ArithmeticException
- ifrhs
is zero.
-
divideInteger
public BigDecimal divideInteger(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the integer part ofthis/rhs
.The same as
divideInteger(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
. - Throws:
java.lang.ArithmeticException
- ifrhs
is zero.
-
divideInteger
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, see
class 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
. - Throws:
java.lang.ArithmeticException
- ifrhs
is zero.java.lang.ArithmeticException
- if the result will not fit in the number of digits specified for the context.
-
max
public BigDecimal max(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the maximum ofthis
andrhs
.The same as
max(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
.
-
max
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 the
compareTo(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
.
-
min
public BigDecimal min(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the minimum ofthis
andrhs
.The same as
min(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
.
-
min
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 the
compareTo(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
.
-
multiply
public BigDecimal multiply(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis*rhs
, using fixed point arithmetic.The same as
add(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.
-
multiply
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
.
-
negate
public BigDecimal negate()
Returns a plainBigDecimal
whose value is-this
.The same as
negate(MathContext)
, where the context isnew MathContext(0, MathContext.PLAIN)
.The length of the decimal part (the scale) of the result will be be
this.scale()
- Returns:
- A
BigDecimal
whose value is-this
.
-
negate
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
.
-
plus
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 as
plus(MathContext)
, where the context isnew MathContext(0, MathContext.PLAIN)
.The length of the decimal part (the scale) of the result will be be
this.scale()
- Returns:
- A
BigDecimal
whose value is+this
.
-
plus
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
.
-
pow
public BigDecimal pow(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis**rhs
, using fixed point arithmetic.The same as
pow(BigDecimal, MathContext)
, where theBigDecimal
isrhs
, and the context isnew MathContext(0, MathContext.PLAIN)
.The parameter is the power to which the
this
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 no
MathContext
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. - Throws:
java.lang.ArithmeticException
- ifrhs
is out of range or is not a whole number.
-
pow
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 the
this
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 the
digits
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
. - Throws:
java.lang.ArithmeticException
- ifrhs
is out of range or is not a whole number.
-
remainder
public BigDecimal remainder(BigDecimal rhs)
Returns a plainBigDecimal
whose value is the remainder ofthis/rhs
, using fixed point arithmetic.The same as
remainder(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. - Throws:
java.lang.ArithmeticException
- ifrhs
is zero.
-
remainder
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, see
class 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
. - Throws:
java.lang.ArithmeticException
- ifrhs
is zero.java.lang.ArithmeticException
- if the integer part of the result will not fit in the number of digits specified for the context.
-
subtract
public BigDecimal subtract(BigDecimal rhs)
Returns a plainBigDecimal
whose value isthis-rhs
, using fixed point arithmetic.The same as
subtract(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.
-
subtract
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
.
-
byteValueExact
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
. - Throws:
java.lang.ArithmeticException
- ifthis
has a non-zero decimal part, or will not fit in abyte
.
-
doubleValue
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 the
BigDecimal
as aString
and then converting it using theDouble(String)
constructor; this can result in values ofDouble.NEGATIVE_INFINITY
orDouble.POSITIVE_INFINITY
.- Specified by:
doubleValue
in classjava.lang.Number
- Returns:
- A
double
corresponding tothis
.
-
equals
public boolean equals(java.lang.Object obj)
Compares thisBigDecimal
withrhs
for equality.If the parameter is
null
, 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 the
String
representations of theBigDecimal
numbers are identical (they have the same characters in the same sequence).The
compareTo(BigDecimal, MathContext)
method should be used for more general comparisons.- Overrides:
equals
in classjava.lang.Object
- 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. - Throws:
java.lang.ClassCastException
- ifrhs
cannot be cast to aBigDecimal
object.- See Also:
compareTo(BigDecimal)
,compareTo(BigDecimal, MathContext)
-
floatValue
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 the
BigDecimal
as aString
and then converting it using theFloat(String)
constructor; this can result in values ofFloat.NEGATIVE_INFINITY
orFloat.POSITIVE_INFINITY
.- Specified by:
floatValue
in classjava.lang.Number
- Returns:
- A
float
corresponding tothis
.
-
format
public java.lang.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 as
DecimalFormat
, 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 the
format
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 using
format(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 - Throws:
java.lang.ArithmeticException
- if the number cannot be laid out as requested.java.lang.IllegalArgumentException
- if a parameter is out of range.- See Also:
toString()
,toCharArray()
-
format
public java.lang.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 as
DecimalFormat
, 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 type
int
. 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 value
MathContext.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 - Throws:
java.lang.ArithmeticException
- if the number cannot be laid out as requested.java.lang.IllegalArgumentException
- if a parameter is out of range.- See Also:
toString()
,toCharArray()
-
hashCode
public int hashCode()
Returns the hashcode for thisBigDecimal
. This hashcode is suitable for use by thejava.util.Hashtable
class.Note that two
BigDecimal
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).- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- An
int
that is the hashcode forthis
.
-
intValue
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.- Specified by:
intValue
in classjava.lang.Number
- Returns:
- An
int
converted fromthis
, truncated and decapitated if necessary.
-
intValueExact
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
. - Throws:
java.lang.ArithmeticException
- ifthis
has a non-zero decimal part, or will not fit in anint
.
-
longValue
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.- Specified by:
longValue
in classjava.lang.Number
- Returns:
- A
long
converted fromthis
, truncated and decapitated if necessary.
-
longValueExact
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
. - Throws:
java.lang.ArithmeticException
- ifthis
has a non-zero decimal part, or will not fit in along
.
-
movePointLeft
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.
-
movePointRight
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.
-
scale
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
.
-
setScale
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 this
BigDecimal
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 this
BigDecimal
then trailing digits will be removed, and in this case anArithmeticException
is thrown if any discarded digits are non-zero.The same as
setScale(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. - Throws:
java.lang.ArithmeticException
- ifscale
is negative.java.lang.ArithmeticException
- if reducing scale would discard non-zero digits.
-
setScale
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 this
BigDecimal
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 this
BigDecimal
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.If
round
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. - Throws:
java.lang.IllegalArgumentException
- ifround
is not a valid rounding mode.java.lang.ArithmeticException
- ifscale
is negative.java.lang.ArithmeticException
- ifround
isMathContext.ROUND_UNNECESSARY
, and reducing scale would discard non-zero digits.
-
shortValueExact
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
. - Throws:
java.lang.ArithmeticException
- ifthis
has a non-zero decimal part, or will not fit in ashort
.
-
signum
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.
-
toBigDecimal
public java.math.BigDecimal toBigDecimal()
Converts thisBigDecimal
to ajava.math.BigDecimal
.This is an exact conversion; the result is the same as if the
BigDecimal
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 the
com.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
.
-
toBigInteger
public java.math.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, use
toBigIntegerExact()
.- Returns:
- The
java.math.BigInteger
equal in value to the integer part of thisBigDecimal
.
-
toBigIntegerExact
public java.math.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
. - Throws:
java.lang.ArithmeticException
- ifthis
has a non-zero decimal part.
-
toCharArray
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
.
-
toString
public java.lang.String toString()
Returns theBigDecimal
as aString
. This returns aString
that exactly represents thisBigDecimal
, as defined in the decimal documentation (seeclass header
).By definition, using the
BigDecimal(String)
constructor on the resultString
will create aBigDecimal
that is exactly equal to the originalBigDecimal
.- Overrides:
toString
in classjava.lang.Object
- Returns:
- The
String
exactly corresponding to thisBigDecimal
. - See Also:
format(int, int)
,format(int, int, int, int, int, int)
,toCharArray()
-
unscaledValue
public java.math.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()
.
-
valueOf
public static BigDecimal valueOf(double dub)
Translates adouble
to aBigDecimal
.Returns a
BigDecimal
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 though
num
had been converted to aString
using theDouble.toString()
method and theBigDecimal(java.lang.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
. - Throws:
java.lang.NumberFormatException
- if the parameter is infinite or not a number.
-
valueOf
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
.
-
valueOf
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)))
A
NumberFormatException
is thrown ifscale
is negative.- Parameters:
lint
- Thelong
to be translated.scale
- Theint
scale to be applied.- Returns:
- The
BigDecimal
equal in value tolint
. - Throws:
java.lang.NumberFormatException
- if the scale is negative.
-
layout
private char[] layout()
-
intcheck
private int intcheck(int min, int max)
-
dodivide
private BigDecimal dodivide(char code, BigDecimal rhs, MathContext set, int scale)
-
bad
private void bad(char[] s)
-
badarg
private void badarg(java.lang.String name, int pos, java.lang.String value)
-
extend
private static final byte[] extend(byte[] inarr, int newlen)
-
byteaddsub
private static final byte[] byteaddsub(byte[] a, int avlen, byte[] b, int bvlen, int m, boolean reuse)
-
diginit
private static final byte[] diginit()
-
clone
private static final BigDecimal clone(BigDecimal dec)
-
checkdigits
private void checkdigits(BigDecimal rhs, int dig)
-
round
private BigDecimal round(MathContext set)
-
round
private BigDecimal round(int len, int mode)
-
allzero
private static final boolean allzero(byte[] array, int start)
-
finish
private BigDecimal finish(MathContext set, boolean strip)
-
-