Immutable, arbitrary-precision signed decimal numbers. A
BigDecimal consists of an arbitrary precision integer
unscaled value and a 32-bit integer
scale. If zero
or positive, the scale is the number of digits to the right of the
decimal point. If negative, the unscaled value of the number is
multiplied by ten to the power of the negation of the scale. The
value of the number represented by the
BigDecimal is
therefore
(unscaledValue × 10-scale).
The
BigDecimal class provides operations for
arithmetic, scale manipulation, rounding, comparison and
format conversion. The
toString() method provides a
canonical representation of a
BigDecimal.
The
BigDecimal class gives its user complete control
over rounding behavior. If no rounding mode is specified and the
exact result cannot be represented, an exception is thrown;
otherwise, calculations can be carried out to a chosen precision
and rounding mode by supplying an appropriate
MathContext
object to the operation. In either case, eight
rounding
modes are provided for the control of rounding. The enumeration
values of the
RoundingMode should be used for such
rounding operations.
This class is a partial ActionScript3 port of the Java
class java.math.BigDecimal originally written by
Josh Bloch, Mike Cowlishaw and Joseph D. Darcy, but relies on a
completely different BigInteger implementation. It provides
externalization methods that are meant to be used with specific GraniteDS
serialization mechanisms.
precision:int [read-only]
The precision of this BigDecimal (the
precision is the number of digits in the unscaled value.)
The precision of a zero value is 1.
Implementation
public function get precision():int
scale:int [read-only]
The scale of this BigDecimal. If zero
or positive, the scale is the number of digits to the right of
the decimal point. If negative, the unscaled value of the
number is multiplied by ten to the power of the negation of the
scale. For example, a scale of -3 means the unscaled
value is multiplied by 1000.
Implementation
public function get scale():int
sign:int [read-only]
The sign of this BigDecimal as an int, ie:
-1, 0 or 1 as the value of this BigDecimal is negative,
zero or positive.
Implementation
public function get sign():int
ulp:BigDecimal [read-only]
The size of an ulp, a unit in the last place, of this
BigDecimal. An ulp of a nonzero BigDecimal
value is the positive distance between this value and the
BigDecimal value next larger in magnitude with the
same number of digits. An ulp of a zero value is numerically
equal to 1 with the scale of this. The result is
stored with the same scale as this so the result
for zero and nonzero values is equal to [1, this.scale].
Implementation
public function get ulp():BigDecimal
unscaledValue:BigInteger [read-only]
A BigInteger whose value is the unscaled
value of this BigDecimal: computes
(this * 10this.scale).
Implementation
public function get unscaledValue():BigInteger
public function BigDecimal(value:* = null)
Constructs a new BigDecimal instance according to the
supplied parameter.
The value parameter may be a String representation of
a decimal value, an int primitive value, a Number,
a Long, a BigInteger or even another
BigDecimal:
String: the string representation consists
of an optional sign, '+' or '-', followed by
a sequence of zero or more decimal digits ("the integer"), optionally
followed by a fraction, optionally followed by an exponent.
The fraction consists of a decimal point followed by zero
or more decimal digits. The string must contain at least one
digit in either the integer or the fraction. The number formed
by the sign, the integer and the fraction is referred to as the
significand.
The exponent consists of the character 'e' or 'E'
followed by one or more decimal digits. The value of the
exponent must lie between -int.MAX_VALUE and
int.MAX_VALUE, inclusive.int: a primitive integer value.Number: a primitive number value. Note that the provided
number is first translated to its String representation in order to parsed
as if it was a String parameter.BigDecimal: the new BigInteger will be an exact copy of
the specified parameter.null: the new BigDecimal will be an exact copy of
the constant BigDecimal.ZERO.
Parameters
| value:* (default = null)BigDecimal.
|
Throws
| NumberFormatError — if the value
parameter is an invalid String representation.
|
| |
| IllegalArgumentError — if the value
parameter is not one of the supported types or if it is
Number.NaN, Number.POSITIVE_INFINITY or
Number.NEGATIVE_INFINITY.
|
public function abs(mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is the absolute value
of this BigDecimal, with rounding according to the
context settings. If context is omitted or null, the returned value
is the absolute value of this BigDecimal with a scale
of this.scale.
Parameters
Returns
Throws
| ArithmeticError — if the result is inexact but
the rounding mode is RoundingMode.UNNECESSARY.
|
public function add(b:*, mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is (this + b),
with rounding according to the context settings. If context is omitted,
no rounding operation is performed.
If either number is zero and the precision setting is nonzero then
the other number, rounded if necessary, is used as the result.
The b parameter may be of any of the supported types as
specified in the BigDecimal constructor documentation.
Parameters
| b:* — value to be added to this BigDecimal.
|
| |
| mc:MathContext (default = null) |
Returns
Throws
| ArithmeticError — if the result is inexact but the
rounding mode is RoundingMode.UNNECESSARY.
|
See also
public function compareTo(b:BigDecimal, unsigned:Boolean = false):int
Compares this BigDecimal with the specified
BigDecimal. Two BigDecimal objects that are
equal in value but have a different scale (like 2.0 and 2.00)
are considered equal by this method. This method is provided
in preference to individual methods for each of the six boolean
comparison operators (<, ==, >, >=, !=, <=). The
suggested idiom for performing these comparisons is:
(x.compareTo(y) <op> 0), where
<op> is one of the six comparison operators.
Parameters
| b:BigDecimal — BigDecimal to which this BigDecimal
is to be compared.
|
| |
| unsigned:Boolean (default = false)true, the comparison will be between
absolute values of this and b.
|
Returns
| int — -1, 0, or 1 as this BigDecimal is numerically
less than, equal to, or greater than b.
|
public function divide(b:*, ... args):BigDecimal
Returns a BigDecimal whose value is (this / b).
Optional parameters are:
- none: the quotient will have a preferred scale of
(this.scale - b.scale): if the exact quotient cannot be
represented (because it has a non-terminating decimal expansion) an
ArithmeticError is thrown.
MathContext: rouding is performed rounding according to
the context settings.RoundingMode: rouding is performed rounding according to
the supplied rounding mode.scale, RoundingMode: scale of the result will be as
specified. If rounding must be performed to generate a result with the
specified scale, the specified rounding mode is applied.
The
b parameter may be of any of the supported types as
specified in the
BigDecimal constructor documentation.
Parameters
| b:* — value by which this BigDecimal is to be divided.
|
| |
| ... args — zero, one or two optional parameters as specified above.
|
Returns
Throws
| ArithmeticError — if b is zero, or if
rounding mode is omitted or equals to RoundingMode.UNNECESSARY
and the exact quotient does not have a terminating decimal expansion or
cannot be scaled according to the scale parameter.
|
See also
public function divideAndRemainder(b:*, mc:MathContext = null):Array
Returns a two-element BigDecimal array containing the
result of divideToIntegralValue followed by the result of
remainder on the two operands calculated with rounding
according to the context settings.
Note that if both the integer quotient and remainder are needed, this
method is faster than using the divideToIntegralValue and
remainder methods separately because the division need only
be carried out once.
The b parameter may be of any of the supported types as
specified in the BigDecimal constructor documentation.
Parameters
| b:* — value by which this BigDecimal is to be divided,
and the remainder computed.
|
| |
| mc:MathContext (default = null) |
Returns
| Array — a two element BigDecimal array: the quotient
(the result of divideToIntegralValue) is the
initial element and the remainder is the final element.
|
Throws
| ArithmeticError — if b is zero or if
the result is inexact but the rounding mode is
RoundingMode.UNNECESSARY, or
mc.precision > 0 and the result of
this.divideToIntgralValue(b) would require a precision
of more than mc.precision digits.
|
See also
public function divideToIntegralValue(b:*, mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is the integer part
of (this / b). Since the integer part of the exact
quotient does not depend on the rounding mode, the rounding mode
does not affect the values returned by this method. The preferred
scale of the result is (this.scale - b.scale()). An
ArithmeticError is thrown if the integer part of the
exact quotient needs more than mc.precision digits.
The b parameter may be of any of the supported types as
specified in the BigDecimal constructor documentation.
Parameters
| b:* — value by which this BigDecimal is to be divided.
|
| |
| mc:MathContext (default = null) |
Returns
Throws
| ArithmeticError — if b is zero
or if mc.precision > 0 and the result requires
a precision of more than mc.precision digits.
|
public function equals(b:*):Boolean
Compares this BigDecimal with the specified object for
equality. Unlike compareTo, this method considers two
BigDecimal objects equal only if they are equal in
value and scale (thus 2.0 is not equal to 2.00 when compared by
this method).
The b parameter may be of any of the supported types as
specified in the BigDecimal constructor documentation.
Parameters
| b:* — b the bject to which this BigDecimal is
to be compared.
|
Returns
| Boolean — true if and only if the specified object is a
BigDecimal whose value and scale are equal to this
BigDecimal's.
|
See also
public function max(b:BigDecimal):BigDecimal
Returns the maximum of this BigDecimal and b.
Parameters
| b:BigDecimal — value with which the maximum is to be computed.
|
Returns
| BigDecimal —
the BigDecimal whose value is the greater of this
BigDecimal and b. If they are equal,
as defined by the compareTo method, this
is returned.
|
See also
public function min(b:BigDecimal):BigDecimal
Returns the minimum of this BigDecimal and b.
Parameters
| b:BigDecimal — value with which the minimum is to be computed.
|
Returns
| BigDecimal —
the BigDecimal whose value is the lesser of this
BigDecimal and b. If they are equal,
as defined by the compareTo method, this
is returned.
|
See also
public function movePointLeft(n:int):BigDecimal
Returns a BigDecimal which is equivalent to this one
with the decimal point moved n places to the left. If
n is non-negative, the call merely adds n
to the scale. If n is negative, the call is equivalent
to movePointRight(-n). The BigDecimal
returned by this call has value (this * 10-n)
and scale max(this.scale + n, 0).
Parameters
| n:int — n number of places to move the decimal point to the left.
|
Returns
| BigDecimal —
a BigDecimal which is equivalent to this one with
the decimal point moved n places to the left.
|
Throws
public function movePointRight(n:int):BigDecimal
Returns a BigDecimal which is equivalent to this one
with the decimal point moved n places to the right.
If n is non-negative, the call merely subtracts
n from the scale. If n is negative, the call
is equivalent to movePointLeft(-n). The BigDecimal
returned by this call has value (this * 10n) and
scale max(this.scale - n, 0).
Parameters
| n:int — n number of places to move the decimal point to the right.
|
Returns
| BigDecimal —
a BigDecimal which is equivalent to this one
with the decimal point moved n places to the right.
|
Throws
public function multiply(b:*, mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is (this * b),
with rounding according to the context settings. If context is omitted,
no rounding operation is performed.
The b parameter may be of any of the supported types as
specified in the BigDecimal constructor documentation.
Parameters
| b:* — value to be multiplied by this BigDecimal.
|
| |
| mc:MathContext (default = null) |
Returns
Throws
| ArithmeticError — if the result is inexact but the
rounding mode is RoundingMode.UNNECESSARY.
|
See also
public function negate(mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is (-this),
with rounding according to the context settings. If context is omitted
or null, no rounding is performed.
Parameters
Returns
Throws
| ArithmeticError — if the result is inexact but
the rounding mode is RoundingMode.UNNECESSARY.
|
public function plus(mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is (+this),
with rounding according to the context settings.
The effect of this method is identical to that of the round()
method.
Parameters
Returns
| BigDecimal —
this, rounded as necessary. A zero result will
have a scale of 0.
|
Throws
| ArithmeticError — if the result is inexact but
the rounding mode is RoundingMode.UNNECESSARY.
|
See also
public function remainder(b:*, mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is (this % b),
with rounding according to the context settings. The MathContext
settings affect the implicit divide used to compute the remainder. The
remainder computation itself is by definition exact. Therefore, the remainder
may contain more than mc.precision digits.
The remainder is given by
this.subtract(this.divideToIntegralValue(b, mc).multiply(b)). Note
that this is not the modulo operation (the result can be negative).
The b parameter may be of any of the supported types as
specified in the BigDecimal constructor documentation.
Parameters
| b:* — value by which this { |
| |
| mc:MathContext (default = null) |
Returns
Throws
| ArithmeticError — if b is zero or if rounding
mode is RoundingMode.UNNECESSARY, or mc.precision > 0
and the result of this.divideToIntgralValue(b) would require a
precision of more than mc.precision digits.
|
See also
public function round(mc:MathContext):BigDecimal
Returns a BigDecimal rounded according to the
MathContext settings. If the precision setting is
0 then no rounding takes place.
Parameters
Returns
| BigDecimal —
a BigDecimal rounded according to the
MathContext settings.
|
Throws
| ArithmeticError — if the rounding mode is
RoundingMode.UNNECESSARY and the
BigDecimal operation would require rounding.
|
See also
public function scaleByPowerOfTen(n:int):BigDecimal
Returns a BigDecimal whose numerical value is equal to
(this * 10n). The scale of the result is
(this.scale - n).
Parameters
Returns
Throws
| ArithmeticError — if the scale would be
outside the range of a 32-bit integer.
|
public function setScale(scale:int, round:RoundingMode = null):BigDecimal
Returns a BigDecimal whose scale is the specified
value, and whose unscaled value is determined by multiplying or
dividing this BigDecimal's unscaled value by the
appropriate power of ten to maintain its overall value. If the
scale is reduced by the operation, the unscaled value must be
divided (rather than multiplied), and the value may be changed;
in this case, the specified rounding mode is applied to the
division.
Parameters
| scale:int — the scale of the BigDecimal value to be
returned.
|
| |
| round:RoundingMode (default = null)null, the
default value of RoundingMode.UNNECESSARY is used).
|
Returns
| BigDecimal —
a BigDecimal whose scale is the specified value,
and whose unscaled value is determined by multiplying or
dividing this BigDecimal's unscaled value by the
appropriate power of ten to maintain its overall value.
|
Throws
| ArithmeticError — if
round == RoundingMode.UNNECESSARY and the specified
scaling operation would require rounding.
|
public function stripTrailingZeros():BigDecimal
Returns a BigDecimal which is numerically equal to
this one but with any trailing zeros removed from the
representation. For example, stripping the trailing zeros from
the BigDecimal value 600.0, which has
[BigInteger, scale] components equals to
[6000, 1], yields 6E2 with [BigInteger,
scale] components equals to [6, -2].
Returns
| BigDecimal —
a numerically equal BigDecimal with any
trailing zeros removed.
|
public function subtract(b:*, mc:MathContext = null):BigDecimal
Returns a BigDecimal whose value is (this - b),
with rounding according to the context settings. If context is omitted,
no rounding operation is performed.
If b is zero then this, rounded if necessary, is used as the
result. If this is zero then the result is b.negate(mc).
The b parameter may be of any of the supported types as
specified in the BigDecimal constructor documentation.
Parameters
| b:* — value to be subtracted from this BigDecimal.
|
| |
| mc:MathContext (default = null) |
Returns
Throws
| ArithmeticError — if the result is inexact but the
rounding mode is RoundingMode.UNNECESSARY.
|
See also
public function toBigInteger():BigInteger
Converts this BigDecimal to a BigInteger: any
fractional part of this BigDecimal will be discarded. Note
that this conversion can lose information about the precision of the
BigDecimal value.
To have an exception thrown if the conversion is inexact (in
other words if a nonzero fractional part is discarded), use the
toBigIntegerExact method.
Returns
See also
public function toBigIntegerExact():BigInteger
Converts this BigDecimal to a BigInteger,
checking for lost information. An exception is thrown if this
BigDecimal has a nonzero fractional part.
Returns
| BigInteger —
this BigDecimal converted to a BigInteger.
|
Throws
public function toInt():int
Converts this BigDecimal to an int: any
fractional part of this BigDecimal will be discarded,
and if the resulting BigInteger is too big to fit in an
int, only the low-order 31 bits are returned, signed as
this BigDecimal was.
Returns
| int — this BigDecimal converted to an int.
|
See also
public function toIntExact():int
Converts this BigDecimal to an int, checking
for lost information. If this BigDecimal has a nonzero
fractional part or is out of the possible range for an int
result then an ArithmeticError is thrown.
Returns
| int — this BigDecimal converted to an int.
|
Throws
| ArithmeticError — if this has a nonzero
fractional part, or will not fit in an int.
|
public function toNumber():Number
Converts this BigDecimal to a Number. This
conversion is done by converting this BigInteger to signed
String representation and constructing a new Number from
this representation: if this BigDecimal has a too great a
magnitude to be represented as a Number, it will be
converted to Number.NEGATIVE_INFINITY or
Number.POSITIVE_INFINITY as appropriate. Note that even when
the return value is finite, this conversion can lose information about
the precision of the BigDecimal value.
Returns
| Number — this BigDecimal converted to a Number.
|
public function toPlainString():String
Returns a string representation of this BigDecimal
without an exponent field. For values with a positive scale,
the number of digits to the right of the decimal point is used
to indicate scale. For values with a zero or negative scale,
the resulting string is generated as if the value were
converted to a numerically equal value with zero scale and as
if all the trailing zeros of the zero scale value were present
in the result.
The entire string is prefixed by a minus sign character '-'
if the unscaled value is less than zero. No sign character is
prefixed if the unscaled value is zero or positive.
Note that if the result of this method is passed to the
BigDecimal constructor, only the numerical value of
this BigDecimal will necessarily be recovered; the
representation of the new BigDecimal may have a
different scale. In particular, if this BigDecimal
has a negative scale, the string resulting from this method will
have a scale of zero when processed by the string constructor.
Returns
| String — a string representation of this BigDecimal
without an exponent field.
|
See also
public function toString(engineering:Boolean = false):String
Returns the string representation of this BigDecimal,
using scientific notation if an exponent is needed.
A standard canonical string form of the BigDecimal
is created as though by the following steps: first, the
absolute value of the unscaled value of the BigDecimal
is converted to a string in base ten using the characters
'0' through '9' with no leading zeros (except if its value is zero,
in which case a single '0' character is used).
Next, an adjusted exponent is calculated; this is the
negated scale, plus the number of characters in the converted
unscaled value, less one. That is,
-scale + (ulength - 1), where ulength is
the length of the absolute value of the unscaled value in decimal
digits (its precision).
If the scale is greater than or equal to zero and the
adjusted exponent is greater than or equal to -6, the
number will be converted to a character form without using
exponential notation. In this case, if the scale is zero then
no decimal point is added and if the scale is positive a
decimal point will be inserted with the scale specifying the
number of characters to the right of the decimal point.
'0' characters are added to the left of the converted
unscaled value as necessary. If no character precedes the
decimal point after this insertion then a conventional
'0' character is prefixed.
Otherwise (that is, if the scale is negative, or the
adjusted exponent is less than -6), the number will be
converted to a character form using exponential notation. In
this case, if the converted BigInteger has more than
one digit a decimal point is inserted after the first digit.
An exponent in character form is then suffixed to the converted
unscaled value (perhaps with inserted decimal point); this
comprises the letter 'E' followed immediately by the
adjusted exponent converted to a character form. The latter is
in base ten, using the characters '0' through '9' with no leading
zeros, and is always prefixed by a sign character '-' if the
adjusted exponent is negative, '+' otherwise.
Finally, the entire string is prefixed by a minus sign character '-'
if the unscaled value is less than zero. No sign character is prefixed
if the unscaled value is zero or positive.
Examples:
For each representation [unscaled value, scale]
on the left, the resulting string is shown on the right.
[123,0] "123"
[-123,0] "-123"
[123,-1] "1.23E+3"
[123,-3] "1.23E+5"
[123,1] "12.3"
[123,5] "0.00123"
[123,10] "1.23E-8"
[-123,12] "-1.23E-10"
Notes:
- There is a one-to-one mapping between the distinguishable
BigDecimal values and the result of this conversion.
That is, every distinguishable BigDecimal value
(unscaled value and scale) has a unique string representation
as a result of using toString(false). If that string
representation is converted back to a BigDecimal using
the BigDecimal constructor, then the original
value will be recovered.
- The string produced for a given number is always the same;
it is not affected by locale.
- The
engineering parameter may be used for
presenting numbers with exponents in engineering notation: if
exponential notation is used, the power of ten is adjusted to
be a multiple of three (engineering notation) such that the
integer part of nonzero values will be in the range 1 through
999.
- The
setScale method may be used for rounding a
BigDecimal so it has a known number of digits after
the decimal point.
Parameters
| engineering:Boolean (default = false) |
Returns
| String — the string representation of this BigDecimal.
|
See also
public static const ONE:BigDecimal
The value 1, with a scale of 0.
public static const TEN:BigDecimal
The value 10, with a scale of 0.
public static const ZERO:BigDecimal
The value 0, with a scale of 0.
