BigDecimal (TotalCrossSDK 6.1.0 API)

java.lang.Object
- totalcross.util.BigDecimal

All Implemented Interfaces:

Comparable
```
public class BigDecimal
extends java.lang.Object
implements Comparable
```
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).

Field Summary

Fields
Modifier and Type	Field and Description
`static BigDecimal`	`ONE` The constant one as a `BigDecimal` with scale zero.
`static int`	`ROUND_CEILING` Rounding mode to round towards positive infinity.
`static int`	`ROUND_DOWN` Rounding mode to round towards zero.
`static int`	`ROUND_FLOOR` Rounding mode to round towards negative infinity.
`static int`	`ROUND_HALF_DOWN` Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case round down.
`static int`	`ROUND_HALF_EVEN` Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case round towards the even neighbor.
`static int`	`ROUND_HALF_UP` Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case round up.
`static int`	`ROUND_UNNECESSARY` Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary.
`static int`	`ROUND_UP` Rounding mode to round away from zero.
`static BigDecimal`	`TEN` The constant ten as a `BigDecimal` with scale zero.
`static BigDecimal`	`ZERO` The constant zero as a `BigDecimal` with scale zero.

Constructor Summary

Constructors
Constructor and Description
`BigDecimal(BigInteger num)` Constructs a new `BigDecimal` whose unscaled value is `num` and whose scale is zero.
`BigDecimal(BigInteger num, int scale)` Constructs a new `BigDecimal` whose unscaled value is `num` and with the given scale.
`BigDecimal(double num)` Translates a `double` into a `BigDecimal` which is the exact decimal representation of the `double`s binary floating-point value.
`BigDecimal(int val)` Constructs a new `BigDecimal` whose unscaled value is `val` and whose scale is zero.
`BigDecimal(long val)` Constructs a new `BigDecimal` whose unscaled value is `val` and whose scale is zero.
`BigDecimal(java.lang.String num)` Translates the string representation of a `BigDecimal` into a `BigDecimal` object.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`BigDecimal`	`abs()`
`BigDecimal`	`add(BigDecimal val)` Returns a `BigDecimal` whose value is `(this + val)`, and whose scale is `max(this.scale(), val.scale())`.
`byte`	`byteValueExact()` Converts this BigDecimal into a byte by first calling longValueExact and then checking that the `long` returned from that method fits into a `byte`.
`int`	`compareTo(BigDecimal val)`
`int`	`compareTo(java.lang.Object other)` Must return > 0 if this object is greater than the other one, < 0 if its smaller, and 0 if they are equal.
`BigDecimal`	`divide(BigDecimal divisor)` Returns a `BigDecimal` whose value is `(this / val)`, and whose scale is `this.scale()`.
`BigDecimal`	`divide(BigDecimal val, int roundingMode)` Returns a `BigDecimal` whose value is `(this / val)`, and whose scale is `this.scale()`.
`BigDecimal`	`divide(BigDecimal val, int newScale, int roundingMode)` Returns a `BigDecimal` whose value is `(this / val)`, and whose scale is as specified.
`BigDecimal[]`	`divideAndRemainder(BigDecimal val)` Returns a `BigDecimal` array, where its first element is the integer part of `this / val`, and its second element is the remainder of the division.
`BigDecimal`	`divideToIntegralValue(BigDecimal val)` Returns a BigDecimal whose value is the integer part of the quotient this / val.
`double`	`doubleValue()`
`boolean`	`equals(java.lang.Object o)`
`int`	`hashCode()`
`int`	`intValue()`
`int`	`intValueExact()` Converts this BigDecimal into an int by first calling longValueExact and then checking that the `long` returned from that method fits into an `int`.
`long`	`longValue()`
`long`	`longValueExact()` Converts this BigDecimal to a long value.
`BigDecimal`	`max(BigDecimal val)`
`BigDecimal`	`min(BigDecimal val)`
`BigDecimal`	`movePointLeft(int n)`
`BigDecimal`	`movePointRight(int n)`
`BigDecimal`	`multiply(BigDecimal val)` Returns a `BigDecimal` whose value is `(this × val)`, and whose scale is `(this.scale() + val.scale())`.
`BigDecimal`	`negate()`
`BigDecimal`	`plus()` Returns this BigDecimal.
`BigDecimal`	`pow(int n)` Returns a BigDecimal whose value is `this` to the power of `n`.
`int`	`precision()` Returns the precision of this BigDecimal (the number of digits in the unscaled value).
`BigDecimal`	`remainder(BigDecimal val)` Returns a `BigDecimal` whose value is the remainder in the quotient `this / val`.
`int`	`scale()`
`BigDecimal`	`scaleByPowerOfTen(int n)` Returns a BigDecimal whose numerical value is the numerical value of this BigDecimal multiplied by 10 to the power of `n`.
`BigDecimal`	`setScale(int scale)`
`BigDecimal`	`setScale(int scale, int roundingMode)`
`short`	`shortValueExact()` Converts this BigDecimal into a short by first calling longValueExact and then checking that the `long` returned from that method fits into a `short`.
`int`	`signum()`
`BigDecimal`	`stripTrailingZeros()` Returns a BigDecimal which is numerically equal to this BigDecimal but with no trailing zeros in the representation.
`BigDecimal`	`subtract(BigDecimal val)` Returns a `BigDecimal` whose value is `(this - val)`, and whose scale is `max(this.scale(), val.scale())`.
`BigInteger`	`toBigInteger()` Converts this BigDecimal to a BigInteger.
`BigInteger`	`toBigIntegerExact()` Converts this BigDecimal into a BigInteger, throwing an ArithmeticException if the conversion is not exact.
`java.lang.String`	`toEngineeringString()` Returns the String representation of this BigDecimal, using engineering notation if necessary.
`java.lang.String`	`toPlainString()` Returns a String representation of this BigDecimal without using scientific notation.
`java.lang.String`	`toString()` Returns the String representation of this BigDecimal, using scientific notation if necessary.
`BigDecimal`	`ulp()` Returns the size of a unit in the last place of this BigDecimal.
`BigInteger`	`unscaledValue()`
`static BigDecimal`	`valueOf(double val)` Returns a new BigDecimal constructed from the BigDecimal(String) constructor using the Double .toString(double) method to obtain the String.
`static BigDecimal`	`valueOf(long val)` Translates a `long` value into a `BigDecimal` object with a scale of zero.
`static BigDecimal`	`valueOf(long val, int scale)` Translates a `long` unscaled value and an `int` scale into a `BigDecimal`.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - ZERO
```
public static final BigDecimal ZERO
```
    The constant zero as a BigDecimal with scale zero.
  - ONE
```
public static final BigDecimal ONE
```
    The constant one as a BigDecimal with scale zero.
  - TEN
```
public static final BigDecimal TEN
```
    The constant ten as a BigDecimal with scale zero.
  - ROUND_UP
```
public static final int ROUND_UP
```
    Rounding mode to round away from zero.
    
    See Also:
    
    Constant Field Values
  - ROUND_DOWN
```
public static final int ROUND_DOWN
```
    Rounding mode to round towards zero.
    
    See Also:
    
    Constant Field Values
  - ROUND_CEILING
```
public static final int ROUND_CEILING
```
    Rounding mode to round towards positive infinity.
    
    See Also:
    
    Constant Field Values
  - ROUND_FLOOR
```
public static final int ROUND_FLOOR
```
    Rounding mode to round towards negative infinity.
    
    See Also:
    
    Constant Field Values
  - ROUND_HALF_UP
```
public static final int ROUND_HALF_UP
```
    Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case round up.
    
    See Also:
    
    Constant Field Values
  - ROUND_HALF_DOWN
```
public static final int ROUND_HALF_DOWN
```
    Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case round down.
    
    See Also:
    
    Constant Field Values
  - ROUND_HALF_EVEN
```
public static final int ROUND_HALF_EVEN
```
    Rounding mode to round towards the "nearest neighbor" unless both neighbors are equidistant, in which case round towards the even neighbor.
    
    See Also:
    
    Constant Field Values
  - ROUND_UNNECESSARY
```
public static final int ROUND_UNNECESSARY
```
    Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - BigDecimal
```
public BigDecimal(java.lang.String num)
           throws InvalidNumberException
```
    Translates the string representation of a BigDecimal into a BigDecimal object.
    
    Parameters:
    
    num - The BigDecimal as a string.
    
    Throws:
    
    InvalidNumberException - If the given number is not a valid representation of a BigDecimal.
  - BigDecimal
```
public BigDecimal(int val)
```
    Constructs a new BigDecimal whose unscaled value is val and whose scale is zero.
    
    Parameters:
    
    val - The value of the new BigDecimal.
  - BigDecimal
```
public BigDecimal(long val)
```
    Constructs a new BigDecimal whose unscaled value is val and whose scale is zero.
    
    Parameters:
    
    val - The value of the new BigDecimal.
  - BigDecimal
```
public BigDecimal(BigInteger num)
```
    Constructs a new BigDecimal whose unscaled value is num and whose scale is zero.
    
    Parameters:
    
    num - The value of the new BigDecimal.
  - BigDecimal
```
public BigDecimal(BigInteger num,
                  int scale)
```
    Constructs a new BigDecimal whose unscaled value is num and with the given scale.
    
    Parameters:
    
    num - The unscaled value of the new BigDecimal.
    
    scale - The given scale.
  - BigDecimal
```
public BigDecimal(double num)
           throws InvalidNumberException
```
    Translates a double into a BigDecimal which is the exact decimal representation of the doubles binary floating-point value. The scale of the returned BigDecimal is the smallest value such that (10^scale × val) is an integer.
    
    Parameters:
    
    num - The number to be converted
    
    Throws:
    
    InvalidNumberException - If the number passed is infinite or NaN.
- Method Detail
  - valueOf
```
public static BigDecimal valueOf(long val)
                          throws InvalidNumberException
```
    Translates a long value into a BigDecimal object with a scale of zero. This "static factory method" is provided in preference to a (long) constructor because it allows for reuse of frequently used BigDecimal values.
    
    Parameters:
    
    val - The value of the BigDecimal.
    
    Returns:
    
    A BigDecimal whose value is val.
    
    Throws:
    
    InvalidNumberException
  - valueOf
```
public static BigDecimal valueOf(long val,
                                 int scale)
                          throws InvalidNumberException
```
    Translates a long unscaled value and an int scale into a BigDecimal. This "static factory method" is provided in preference to a (long, int) constructor because it allows for reuse of frequently used BigDecimal values.
    
    Parameters:
    
    scale - Scale of the BigDecimal.
    
    Returns:
    
    A BigDecimal whose value is (unscaledVal × 10^-scale).
    
    Throws:
    
    InvalidNumberException
  - add
```
public BigDecimal add(BigDecimal val)
```
    Returns a BigDecimal whose value is (this + val), and whose scale is max(this.scale(), val.scale()).
    
    Parameters:
    
    val - The value to be added to this BigDecimal.
    
    Returns:
    
    (this + val).
  - subtract
```
public BigDecimal subtract(BigDecimal val)
```
    Returns a BigDecimal whose value is (this - val), and whose scale is max(this.scale(), val.scale()).
    
    Parameters:
    
    val - The value to be subtracted from this BigDecimal.
    
    Returns:
    
    (this - val).
  - multiply
```
public BigDecimal multiply(BigDecimal val)
```
    Returns a BigDecimal whose value is (this × val), and whose scale is (this.scale() + val.scale()).
    
    Parameters:
    
    val - The value to be multiplied by this BigDecimal.
    
    Returns:
    
    (this * val).
  - divide
```
public BigDecimal divide(BigDecimal val,
                         int roundingMode)
                  throws java.lang.ArithmeticException,
                         java.lang.IllegalArgumentException
```
    Returns a BigDecimal whose value is (this / val), and whose scale is this.scale(). If rounding must be performed to generate a result with the given scale, the specified rounding mode is applied.
    
    Parameters:
    
    val - The value by which this BigDecimal is to be divided.
    
    roundingMode - The rounding mode to apply.
    
    Returns:
    
    (this / val).
    
    Throws:
    
    java.lang.ArithmeticException - If val == 0, or roundingMode == ROUND_UNNECESSARY and this.scale() is insufficient to represent the result of the division exactly.
    
    java.lang.IllegalArgumentException - If roundingMode does not represent a valid rounding mode.
  - divide
```
public BigDecimal divide(BigDecimal val,
                         int newScale,
                         int roundingMode)
                  throws java.lang.ArithmeticException,
                         java.lang.IllegalArgumentException
```
    Returns a BigDecimal whose value is (this / val), and whose scale is as specified. If rounding must be performed to generate a result with the given scale, the specified rounding mode is applied.
    
    Parameters:
    
    val - The value by which this BigDecimal is to be divided.
    
    roundingMode - The rounding mode to apply.
    
    Returns:
    
    (this / val).
    
    Throws:
    
    java.lang.ArithmeticException - If val == 0, or roundingMode == ROUND_UNNECESSARY and this.scale() is insufficient to represent the result of the division exactly.
    
    java.lang.IllegalArgumentException - If roundingMode does not represent a valid rounding mode.
  - divide
```
public BigDecimal divide(BigDecimal divisor)
                  throws java.lang.ArithmeticException
```
    Returns a BigDecimal whose value is (this / val), and whose scale is this.scale(). If rounding must be performed to generate a result with the given scale, an ArithmeticException is thrown.
    
    Parameters:
    
    divisor - The value by which this BigDecimal is to be divided.
    
    Returns:
    
    (this / val).
    
    Throws:
    
    java.lang.ArithmeticException - If val == 0, or this.scale() is insufficient to represent the result of the division exactly.
  - remainder
```
public BigDecimal remainder(BigDecimal val)
                     throws java.lang.ArithmeticException,
                            java.lang.IllegalArgumentException,
                            InvalidNumberException
```
    Returns a BigDecimal whose value is the remainder in the quotient this / val. This is obtained by subtract(divideToIntegralValue(val).multiply(val)).
    
    Parameters:
    
    val - The divisor.
    
    Returns:
    
    A BigDecimal whose value is the remainder
    
    Throws:
    
    InvalidNumberException - If an internal method throws it.
    
    java.lang.IllegalArgumentException - If an internal method throws it.
    
    java.lang.ArithmeticException - If val == 0.
  - divideAndRemainder
```
public BigDecimal[] divideAndRemainder(BigDecimal val)
                                throws java.lang.ArithmeticException,
                                       java.lang.IllegalArgumentException,
                                       InvalidNumberException
```
    Returns a BigDecimal array, where its first element is the integer part of this / val, and its second element is the remainder of the division.
    
    Parameters:
    
    val - The divisor.
    
    Returns:
    
    The above described BigDecimal array.
    
    Throws:
    
    InvalidNumberException - If an internal method throws it.
    
    java.lang.IllegalArgumentException - If an internal method throws it.
    
    java.lang.ArithmeticException - If val == 0.
  - divideToIntegralValue
```
public BigDecimal divideToIntegralValue(BigDecimal val)
                                 throws java.lang.ArithmeticException,
                                        java.lang.IllegalArgumentException,
                                        InvalidNumberException
```
    Returns a BigDecimal whose value is the integer part of the quotient this / val. The preferred scale is this.scale - val.scale.
    
    Parameters:
    
    val - the divisor
    
    Returns:
    
    a BigDecimal whose value is the integer part of this / val.
    
    Throws:
    
    InvalidNumberException
    
    java.lang.IllegalArgumentException
    
    java.lang.ArithmeticException
    
    java.lang.ArithmeticException - if val == 0
  - compareTo
```
public int compareTo(BigDecimal val)
```
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - max
```
public BigDecimal max(BigDecimal val)
```
  - min
```
public BigDecimal min(BigDecimal val)
```
  - movePointLeft
```
public BigDecimal movePointLeft(int n)
```
  - movePointRight
```
public BigDecimal movePointRight(int n)
```
  - signum
```
public int signum()
```
  - scale
```
public int scale()
```
  - unscaledValue
```
public BigInteger unscaledValue()
```
  - abs
```
public BigDecimal abs()
```
  - negate
```
public BigDecimal negate()
```
  - plus
```
public BigDecimal plus()
```
    Returns this BigDecimal. This is included for symmetry with the method negate().
    
    Returns:
    
    this
  - precision
```
public int precision()
```
    Returns the precision of this BigDecimal (the number of digits in the unscaled value). The precision of a zero value is 1.
    
    Returns:
    
    the number of digits in the unscaled value, or 1 if the value is zero.
  - toString
```
public java.lang.String toString()
```
    Returns the String representation of this BigDecimal, using scientific notation if necessary. The following steps are taken to generate the result: 1. the BigInteger unscaledValue's toString method is called and if scale == 0 is returned. 2. an int adjExp is created which is equal to the negation of scale plus the number of digits in the unscaled value, minus one. 3. if scale >= 0 && adjExp >= -6 then we represent this BigDecimal without scientific notation. A decimal is added if the scale is positive and zeros are prepended as necessary. 4. if scale is negative or adjExp is less than -6 we use scientific notation. If the unscaled value has more than one digit, a decimal as inserted after the first digit, the character 'E' is appended and adjExp is appended.
    
    Overrides:
    
    toString in class java.lang.Object
  - toEngineeringString
```
public java.lang.String toEngineeringString()
```
    Returns the String representation of this BigDecimal, using engineering notation if necessary. This is similar to toString() but when exponents are used the exponent is made to be a multiple of 3 such that the integer part is between 1 and 999.
    
    Returns:
    
    a String representation of this BigDecimal in engineering notation
  - toPlainString
```
public java.lang.String toPlainString()
```
    Returns a String representation of this BigDecimal without using scientific notation. This is how toString() worked for releases 1.4 and previous. Zeros may be added to the end of the String. For example, an unscaled value of 1234 and a scale of -3 would result in the String 1234000, but the toString() method would return 1.234E+6.
    
    Returns:
    
    a String representation of this BigDecimal
  - toBigInteger
```
public BigInteger toBigInteger()
```
    Converts this BigDecimal to a BigInteger. Any fractional part will be discarded.
    
    Returns:
    
    a BigDecimal whose value is equal to floor[this]
  - toBigIntegerExact
```
public BigInteger toBigIntegerExact()
```
    Converts this BigDecimal into a BigInteger, throwing an ArithmeticException if the conversion is not exact.
    
    Returns:
    
    a BigInteger whose value is equal to the value of this BigDecimal
  - intValue
```
public int intValue()
```
  - stripTrailingZeros
```
public BigDecimal stripTrailingZeros()
                              throws InvalidNumberException
```
    Returns a BigDecimal which is numerically equal to this BigDecimal but with no trailing zeros in the representation. For example, if this BigDecimal has [unscaledValue, scale] = [6313000, 4] this method returns a BigDecimal with [unscaledValue, scale] = [6313, 1]. As another example, [12400, -2] would become [124, -4].
    
    Returns:
    
    a numerically equal BigDecimal with no trailing zeros
    
    Throws:
    
    InvalidNumberException
  - longValue
```
public long longValue()
```
  - doubleValue
```
public double doubleValue()
                   throws InvalidNumberException
```
    Throws:
    
    InvalidNumberException
  - setScale
```
public BigDecimal setScale(int scale)
                    throws java.lang.ArithmeticException
```
    Throws:
    
    java.lang.ArithmeticException
  - setScale
```
public BigDecimal setScale(int scale,
                           int roundingMode)
                    throws java.lang.ArithmeticException,
                           java.lang.IllegalArgumentException
```
    Throws:
    
    java.lang.ArithmeticException
    
    java.lang.IllegalArgumentException
  - valueOf
```
public static BigDecimal valueOf(double val)
                          throws InvalidNumberException
```
    Returns a new BigDecimal constructed from the BigDecimal(String) constructor using the Double .toString(double) method to obtain the String.
    
    Parameters:
    
    val - the double value used in Double .toString(double)
    
    Returns:
    
    a BigDecimal representation of val
    
    Throws:
    
    InvalidNumberException - if val is NaN or infinite
  - scaleByPowerOfTen
```
public BigDecimal scaleByPowerOfTen(int n)
```
    Returns a BigDecimal whose numerical value is the numerical value of this BigDecimal multiplied by 10 to the power of n.
    
    Parameters:
    
    n - the power of ten
    
    Returns:
    
    the new BigDecimal
  - pow
```
public BigDecimal pow(int n)
```
    Returns a BigDecimal whose value is this to the power of n.
    
    Parameters:
    
    n - the power
    
    Returns:
    
    the new BigDecimal
  - ulp
```
public BigDecimal ulp()
```
    Returns the size of a unit in the last place of this BigDecimal. This returns a BigDecimal with [unscaledValue, scale] = [1, this.scale()].
    
    Returns:
    
    the size of a unit in the last place of this.
  - longValueExact
```
public long longValueExact()
```
    Converts this BigDecimal to a long value.
    
    Returns:
    
    the long value
    
    Throws:
    
    java.lang.ArithmeticException - if rounding occurs or if overflow occurs
  - intValueExact
```
public int intValueExact()
```
    Converts this BigDecimal into an int by first calling longValueExact and then checking that the long returned from that method fits into an int.
    
    Returns:
    
    an int whose value is this
    
    Throws:
    
    java.lang.ArithmeticException - if this BigDecimal has a fractional part or is too large to fit into an int.
  - byteValueExact
```
public byte byteValueExact()
```
    Converts this BigDecimal into a byte by first calling longValueExact and then checking that the long returned from that method fits into a byte.
    
    Returns:
    
    a byte whose value is this
    
    Throws:
    
    java.lang.ArithmeticException - if this BigDecimal has a fractional part or is too large to fit into a byte.
  - shortValueExact
```
public short shortValueExact()
```
    Converts this BigDecimal into a short by first calling longValueExact and then checking that the long returned from that method fits into a short.
    
    Returns:
    
    a short whose value is this
    
    Throws:
    
    java.lang.ArithmeticException - if this BigDecimal has a fractional part or is too large to fit into a short.
  - compareTo
```
public int compareTo(java.lang.Object other)
              throws java.lang.ClassCastException
```
    Description copied from interface: Comparable
    
    Must return > 0 if this object is greater than the other one, < 0 if its smaller, and 0 if they are equal.
    
    Specified by:
    
    compareTo in interface Comparable
    
    Throws:
    
    java.lang.ClassCastException

Class BigDecimal

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZERO

ONE

TEN

ROUND_UP

ROUND_DOWN

ROUND_CEILING

ROUND_FLOOR

ROUND_HALF_UP

ROUND_HALF_DOWN

ROUND_HALF_EVEN

ROUND_UNNECESSARY

Constructor Detail

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

BigDecimal

Method Detail

valueOf

valueOf

add

subtract

multiply

divide

divide

divide

remainder

divideAndRemainder

divideToIntegralValue

compareTo

equals

hashCode

max

min

movePointLeft

movePointRight

signum

scale

unscaledValue

abs

negate

plus

precision

toString

toEngineeringString

toPlainString

toBigInteger

toBigIntegerExact

intValue

stripTrailingZeros

longValue

doubleValue

setScale

setScale

valueOf

scaleByPowerOfTen

pow

ulp

longValueExact

intValueExact

byteValueExact

shortValueExact

compareTo