Class BigDecimal
- All Implemented Interfaces:
Serializable
,Comparable<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
[This URL will change.]
Operator methods
Operations on 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:
- 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
, and java.math.BigDecimal
in Java 1.1 and Java 1.2.
- Author:
- Mike Cowlishaw
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final BigDecimal
TheBigDecimal
constant "1".static final int
Rounding mode to round to a more positive number.static final int
Rounding mode to round towards zero.static final int
Rounding mode to round to a more negative number.static final int
Rounding mode to round to nearest neighbor, where an equidistant value is rounded down.static final int
Rounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.static final int
Rounding mode to round to nearest neighbor, where an equidistant value is rounded up.static final int
Rounding mode to assert that no rounding is necessary.static final int
Rounding mode to round away from zero.static final BigDecimal
TheBigDecimal
constant "10".static final BigDecimal
TheBigDecimal
constant "0". -
Constructor Summary
ConstructorsConstructorDescriptionBigDecimal
(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
(String string) Constructs aBigDecimal
object from aString
.BigDecimal
(BigDecimal bd) Constructs aBigDecimal
object from ajava.math.BigDecimal
.BigDecimal
(BigInteger bi) Constructs aBigDecimal
object from aBigInteger
, with scale 0.BigDecimal
(BigInteger bi, int scale) Constructs aBigDecimal
object from aBigInteger
and a scale. -
Method Summary
Modifier and TypeMethodDescriptionabs()
Returns a plainBigDecimal
whose value is the absolute value of thisBigDecimal
.abs
(MathContext set) Returns aBigDecimal
whose value is the absolute value of thisBigDecimal
.add
(BigDecimal rhs) Returns a plainBigDecimal
whose value isthis+rhs
, using fixed point arithmetic.add
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value isthis+rhs
.byte
Converts thisBigDecimal
to abyte
.int
compareTo
(BigDecimal rhs) Compares thisBigDecimal
to another, using unlimited precision.int
compareTo
(BigDecimal rhs, MathContext set) Compares thisBigDecimal
to another.divide
(BigDecimal rhs) Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic.divide
(BigDecimal rhs, int round) Returns a plainBigDecimal
whose value isthis/rhs
, using fixed point arithmetic and a rounding mode.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.divide
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value isthis/rhs
.divideInteger
(BigDecimal rhs) Returns a plainBigDecimal
whose value is the integer part ofthis/rhs
.divideInteger
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value is the integer part ofthis/rhs
.double
Converts thisBigDecimal
to adouble
.boolean
Compares thisBigDecimal
withrhs
for equality.float
Converts thisBigDecimal
to afloat
.format
(int before, int after) Returns theString
representation of thisBigDecimal
, modified by layout parameters.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
.int
intValue()
Converts thisBigDecimal
to anint
.int
Converts thisBigDecimal
to anint
.long
Converts thisBigDecimal
to along
.long
Converts thisBigDecimal
to along
.max
(BigDecimal rhs) Returns a plainBigDecimal
whose value is the maximum ofthis
andrhs
.max
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value is the maximum ofthis
andrhs
.min
(BigDecimal rhs) Returns a plainBigDecimal
whose value is the minimum ofthis
andrhs
.min
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value is the minimum ofthis
andrhs
.movePointLeft
(int n) Returns a plainBigDecimal
whose decimal point has been moved to the left by a specified number of positions.movePointRight
(int n) Returns a plainBigDecimal
whose decimal point has been moved to the right by a specified number of positions.multiply
(BigDecimal rhs) Returns a plainBigDecimal
whose value isthis*rhs
, using fixed point arithmetic.multiply
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value isthis*rhs
.negate()
Returns a plainBigDecimal
whose value is-this
.negate
(MathContext set) Returns aBigDecimal
whose value is-this
.plus()
Returns a plainBigDecimal
whose value is+this
.plus
(MathContext set) Returns aBigDecimal
whose value is+this
.pow
(BigDecimal rhs) Returns a plainBigDecimal
whose value isthis**rhs
, using fixed point arithmetic.pow
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value isthis**rhs
.remainder
(BigDecimal rhs) Returns a plainBigDecimal
whose value is the remainder ofthis/rhs
, using fixed point arithmetic.remainder
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value is the remainder ofthis/rhs
.int
scale()
Returns the scale of thisBigDecimal
.setScale
(int scale) Returns a plainBigDecimal
with a given scale.setScale
(int scale, int round) Returns a plainBigDecimal
with a given scale.short
Converts thisBigDecimal
to ashort
.int
signum()
Returns the sign of thisBigDecimal
, as anint
.subtract
(BigDecimal rhs) Returns a plainBigDecimal
whose value isthis-rhs
, using fixed point arithmetic.subtract
(BigDecimal rhs, MathContext set) Returns aBigDecimal
whose value isthis-rhs
.Converts thisBigDecimal
to ajava.math.BigDecimal
.Converts thisBigDecimal
to ajava.math.BigInteger
.Converts thisBigDecimal
to ajava.math.BigInteger
.char[]
Returns theBigDecimal
as a character array.toString()
Returns theBigDecimal
as aString
.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.Methods inherited from class java.lang.Number
byteValue, shortValue
-
Field Details
-
ZERO
TheBigDecimal
constant "0".- See Also:
-
ONE
TheBigDecimal
constant "1".- See Also:
-
TEN
TheBigDecimal
constant "10".- See Also:
-
ROUND_CEILING
public static final int ROUND_CEILINGRounding mode to round to a more positive number.- See Also:
-
ROUND_DOWN
public static final int ROUND_DOWNRounding mode to round towards zero.- See Also:
-
ROUND_FLOOR
public static final int ROUND_FLOORRounding mode to round to a more negative number.- See Also:
-
ROUND_HALF_DOWN
public static final int ROUND_HALF_DOWNRounding mode to round to nearest neighbor, where an equidistant value is rounded down.- See Also:
-
ROUND_HALF_EVEN
public static final int ROUND_HALF_EVENRounding mode to round to nearest neighbor, where an equidistant value is rounded to the nearest even neighbor.- See Also:
-
ROUND_HALF_UP
public static final int ROUND_HALF_UPRounding mode to round to nearest neighbor, where an equidistant value is rounded up.- See Also:
-
ROUND_UNNECESSARY
public static final int ROUND_UNNECESSARYRounding mode to assert that no rounding is necessary.- See Also:
-
ROUND_UP
public static final int ROUND_UPRounding mode to round away from zero.- See Also:
-
-
Constructor Details
-
BigDecimal
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
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
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:
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:
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:
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:
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
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:
NumberFormatException
- If the parameter is not a valid number.
-
-
Method Details
-
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
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
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
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
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 interfaceComparable<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
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
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:
ArithmeticException
- Ifrhs
is zero.
-
divide
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:
IllegalArgumentException
- ifround
is not a valid rounding mode.ArithmeticException
- ifrhs
is zero.ArithmeticException
- ifround
isMathContext.ROUND_UNNECESSARY
andthis.scale()
is insufficient to represent the result exactly.
-
divide
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:
IllegalArgumentException
- ifround
is not a valid rounding mode.ArithmeticException
- ifrhs
is zero.ArithmeticException
- ifscale
is negative.ArithmeticException
- ifround
isMathContext.ROUND_UNNECESSARY
andscale
is insufficient to represent the result exactly.
-
divide
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:
ArithmeticException
- ifrhs
is zero.
-
divideInteger
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:
ArithmeticException
- ifrhs
is zero.
-
divideInteger
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:
ArithmeticException
- ifrhs
is zero.ArithmeticException
- if the result will not fit in the number of digits specified for the context.
-
max
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
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
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
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
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
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
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
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
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
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
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:
ArithmeticException
- ifrhs
is out of range or is not a whole number.
-
pow
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:
ArithmeticException
- ifrhs
is out of range or is not a whole number.
-
remainder
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:
ArithmeticException
- ifrhs
is zero.
-
remainder
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:
ArithmeticException
- ifrhs
is zero.ArithmeticException
- if the integer part of the result will not fit in the number of digits specified for the context.
-
subtract
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
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:
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 classNumber
- Returns:
- A
double
corresponding tothis
.
-
equals
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 classObject
- 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:
ClassCastException
- ifrhs
cannot be cast to aBigDecimal
object.- See Also:
-
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 classNumber
- Returns:
- A
float
corresponding tothis
.
-
format
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:
ArithmeticException
- if the number cannot be laid out as requested.IllegalArgumentException
- if a parameter is out of range.- See Also:
-
format
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:
ArithmeticException
- if the number cannot be laid out as requested.IllegalArgumentException
- if a parameter is out of range.- See Also:
-
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). -
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. -
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:
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. -
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:
ArithmeticException
- ifthis
has a non-zero decimal part, or will not fit in along
.
-
movePointLeft
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
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
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:
ArithmeticException
- ifscale
is negative.ArithmeticException
- if reducing scale would discard non-zero digits.
-
setScale
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:
IllegalArgumentException
- ifround
is not a valid rounding mode.ArithmeticException
- ifscale
is negative.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:
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
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
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
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:
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
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
. -
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
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:
NumberFormatException
- if the parameter is infinite or not a number.
-
valueOf
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
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:
NumberFormatException
- if the scale is negative.
-