Decimal (LSPS 3.6 SDK)

java.lang.Object
- java.lang.Number
- - com.whitestein.lsps.lang.Decimal

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Decimal>
```
public final class Decimal
extends java.lang.Number
implements java.io.Serializable, java.lang.Comparable<Decimal>
```
Immutable, arbitrary-precision signed decimal numbers with scale limited to DecimalType.MAX_SCALE. This class has basically the same functionality as BigDecimal, but it represents equal numbers with different notations in canonical form and thus they are always equal (e.g. numbers 1.0 and 1.00 are equal).

Author:

rba

See Also:

BigDecimal, Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

static Decimal MINUS_ONE
Decimal with value -1.

static Decimal ONE
Decimal with value 1.

static Decimal ZERO
Decimal with value 0.

Fields
Modifier and Type	Field and Description
`static Decimal`	`MINUS_ONE` Decimal with value -1.
`static Decimal`	`ONE` Decimal with value 1.
`static Decimal`	`ZERO` Decimal with value 0.

Constructor Summary

Constructors
Constructor and Description
`Decimal(java.math.BigDecimal val)` Creates new instance of `Decimal`.
`Decimal(java.math.BigInteger val)` Creates new instance of `Decimal`.
`Decimal(char[] val)` Creates new instance of `Decimal`.
`Decimal(double val)` Creates new instance of `Decimal`.
`Decimal(long val)` Creates new instance of `Decimal`.
`Decimal(java.lang.String val)` Creates new instance of `Decimal`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Decimal`	`abs()` Returns a `Decimal` whose value is the absolute value of this `Decimal`, and whose scale is `this.scale()`.
`Decimal`	`add(Decimal augend)` Returns a `Decimal` whose value is `(this + augend)`.
`int`	`compareTo(Decimal val)` Compares this `Decimal` with the specified `Decimal`.
`Decimal`	`divide(Decimal divisor)` Returns a `Decimal` whose value is `(this / divisor)`.
`Decimal`	`divideToIntegralValue(Decimal divisor)` Returns a `Decimal` whose value is the integer part of the quotient `(this / divisor)` rounded down.
`double`	`doubleValue()` Converts this `Decimal` to a `double`.
`boolean`	`equals(java.lang.Object obj)` Compares this `Decimal` with the specified `Object` for equality.
`float`	`floatValue()` Converts this `Decimal` to a `float`.
`int`	`hashCode()` Returns the hash code for this `Decimal`.
`int`	`intValue()` Converts this `Decimal` to an `int`.
`int`	`intValueExact()` Converts this `Decimal` to an `int`, checking for lost information.
`boolean`	`isInteger()` Returns true if this `Decimal` is an integer, i.e.
`long`	`longValue()` Converts this `Decimal` to a `long`.
`long`	`longValueExact()` Converts this `Decimal` to a `long`, checking for lost information.
`Decimal`	`multiply(Decimal multiplicand)` Returns a `Decimal` whose value is `(this × multiplicand)`.
`Decimal`	`negate()` Returns a `Decimal` whose value is `(-this)`.
`Decimal`	`pow(int n)` Returns a `Decimal` whose value is `(this<sup>n</sup>)`, The power is computed exactly, to unlimited precision.
`int`	`precision()` Returns the precision of this `Decimal`.
`Decimal`	`remainder(Decimal divisor)` Returns a `Decimal` whose value is `(this % divisor)`.
`int`	`scale()` Returns the scale of this `Decimal`.
`Decimal`	`setScale(int newScale, java.math.RoundingMode roundingMode)` Returns a `Decimal` whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this `Decimal`'s unscaled value by the appropriate power of ten to maintain its overall value.
`int`	`signum()` Returns the signum function of this `Decimal`.
`Decimal`	`subtract(Decimal subtrahend)` Returns a `Decimal` whose value is `(this - subtrahend)`.
`java.math.BigDecimal`	`toBigDecimal()` Converts this `Decimal` to a `BigDecimal`.
`java.math.BigInteger`	`toBigInteger()` Converts this `Decimal` to a `BigInteger`.
`java.math.BigInteger`	`toBigIntegerExact()` Converts this `Decimal` to a `BigInteger`, checking for lost information.
`java.lang.String`	`toPlainString()` Returns a string representation of this `Decimal` without an exponent field.
`java.lang.String`	`toString()` This method is identical to `BigDecimal.toString()`; only in the case when the scale is in the range [-1, -20], the scale is extended to 0 by adding zeros and only after then the `BigDecimal.toString()` method is performed.
`java.math.BigInteger`	`unscaledValue()` Returns a `BigInteger` whose value is the unscaled value of this `Decimal`.
`static Decimal`	`valueOf(double val)` Translates a `double` into a `Decimal`, using the `double`'s canonical string representation provided by the `Double.toString(double)` method.
`static Decimal`	`valueOf(float val)` Translates a `float` into a `Decimal`, using the `float`'s canonical string representation provided by the `Float.toString(float)` method.
`static Decimal`	`valueOf(int val)` Translates a `int` value into a `Decimal` with a scale of zero.
`static Decimal`	`valueOf(long val)` Translates a `long` value into a `Decimal` with a scale of zero.
`static Decimal`	`valueOf(java.lang.Number number)` Attempts to construct the decimal using a best-fit algorithm: Long, Integer, Short, Byte uses the `valueOf(long)` method Float uses `valueOf(float)` Double uses `valueOf(double)` BigInteger uses `Decimal(java.math.BigInteger)` BigDecimal uses `Decimal(java.math.BigDecimal)` Decimal just return the number All other numbers are rejected to avoid precision loss.

Methods inherited from class java.lang.Number
byteValue, shortValue

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

- Field Detail
 - ZERO
```
public static final Decimal ZERO
```
 Decimal with value 0.
 - ONE
```
public static final Decimal ONE
```
 Decimal with value 1.
 - MINUS_ONE
```
public static final Decimal MINUS_ONE
```
 Decimal with value -1.
- Constructor Detail
 - Decimal
```
public Decimal(long val)
```
 Creates new instance of Decimal.
 
 Parameters:
 
 val -
 - Decimal
```
public Decimal(double val)
```
 Creates new instance of Decimal.
 
 Parameters:
 
 val -
 
 Throws:
 
 java.lang.NumberFormatException - if val is infinite or NaN
 - Decimal
```
public Decimal(java.lang.String val)
```
 Creates new instance of Decimal.
 
 Parameters:
 
 val -
 
 Throws:
 
 java.lang.NumberFormatException - if val is not a valid representation of a Decimal
 
 java.lang.NullPointerException - if val is null
 - Decimal
```
public Decimal(char[] val)
```
 Creates new instance of Decimal.
 
 Parameters:
 
 val -
 
 Throws:
 
 java.lang.NumberFormatException - if val is not a valid representation of a Decimal
 
 java.lang.NullPointerException - if val is null
 - Decimal
```
public Decimal(java.math.BigInteger val)
```
 Creates new instance of Decimal.
 
 Parameters:
 
 val -
 
 Throws:
 
 java.lang.NullPointerException - if val is null
 - Decimal
```
public Decimal(java.math.BigDecimal val)
```
 Creates new instance of Decimal.
 
 Parameters:
 
 val -
- Method Detail
 - abs
```
public Decimal abs()
```
 Returns a Decimal whose value is the absolute value of this Decimal, and whose scale is this.scale().
 
 Returns:
 
 abs(this)
 - add
```
public Decimal add(Decimal augend)
```
 Returns a Decimal whose value is (this + augend).
 
 Parameters:
 
 augend - value to be added to this Decimal.
 
 Returns:
 
 this + augend
 
 Throws:
 
 java.lang.NullPointerException - if augend is null
 - subtract
```
public Decimal subtract(Decimal subtrahend)
```
 Returns a Decimal whose value is (this - subtrahend).
 
 Parameters:
 
 subtrahend - value to be subtracted from this Decimal.
 
 Returns:
 
 this - subtrahend
 
 Throws:
 
 java.lang.NullPointerException - if subtrahend is null
 - multiply
```
public Decimal multiply(Decimal multiplicand)
```
 Returns a Decimal whose value is (this × multiplicand).
 
 Parameters:
 
 multiplicand - value to be multiplied by this Decimal.
 
 Returns:
 
 this * multiplicand
 
 Throws:
 
 java.lang.NullPointerException - if multiplicand is null
 - divide
```
public Decimal divide(Decimal divisor)
```
 Returns a Decimal whose value is (this / divisor).
 
 Parameters:
 
 divisor - value by which this Decimal is to be divided.
 
 Returns:
 
 this / divisor
 
 Throws:
 
 java.lang.ArithmeticException - if divisor is zero
 
 java.lang.NullPointerException - if divisor is null
 - divideToIntegralValue
```
public Decimal divideToIntegralValue(Decimal divisor)
```
 Returns a Decimal whose value is the integer part of the quotient (this / divisor) rounded down.
 
 Parameters:
 
 divisor - value by which this Decimal is to be divided.
 
 Returns:
 
 The integer part of this / divisor.
 
 Throws:
 
 java.lang.ArithmeticException - if divisor==0
 
 java.lang.ArithmeticException - if divisor is zero
 
 java.lang.NullPointerException - if divisor is null
 - negate
```
public Decimal negate()
```
 Returns a Decimal whose value is (-this).
 
 Returns:
 
 -this.
 - remainder
```
public Decimal remainder(Decimal divisor)
```
 Returns a Decimal whose value is (this % divisor).
 The remainder is given by this.subtract(this.divideToIntegralValue(divisor).multiply(divisor)). Note that this is not the modulo operation (the result can be negative).
 
 Parameters:
 
 divisor - value by which this Decimal is to be divided.
 
 Returns:
 
 this % divisor.
 
 Throws:
 
 java.lang.ArithmeticException - if divisor is zero
 
 java.lang.NullPointerException - if divisor is null
 - pow
```
public Decimal pow(int n)
```
 Returns a Decimal whose value is (thisn), The power is computed exactly, to unlimited precision.
 The parameter n must be in the range 0 through 999999999, inclusive. ZERO.pow(0) returns ONE.
 
 Parameters:
 
 n - power to raise this Decimal to.
 
 Returns:
 
 thisn
 
 Throws:
 
 java.lang.ArithmeticException - if n is out of range.
 - signum
```
public int signum()
```
 Returns the signum function of this Decimal.
 
 Returns:
 
 -1, 0, or 1 as the value of this Decimal is negative, zero, or positive.
 - scale
```
public int scale()
```
 Returns the scale of this Decimal. 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.
 
 Returns:
 
 the scale of this Decimal.
 - setScale
```
public Decimal setScale(int newScale,
 java.math.RoundingMode roundingMode)
```
 Returns a Decimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this Decimal'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:
 
 newScale - scale of the Decimal value to be returned.
 
 roundingMode - The rounding mode to apply.
 
 Returns:
 
 a Decimal whose scale is the specified value, and whose unscaled value is determined by multiplying or dividing this Decimal's unscaled value by the appropriate power of ten to maintain its overall value.
 
 Throws:
 
 java.lang.ArithmeticException - if roundingMode==UNNECESSARY and the specified scaling operation would require rounding.
 
 java.lang.NullPointerException - if roundingMode is null
 
 See Also:
 
 RoundingMode
 - precision
```
public int precision()
```
 Returns the precision of this Decimal. (The precision is the number of digits in the unscaled value.)
 The precision of a zero value is 1.
 
 Returns:
 
 the precision of this Decimal.
 - unscaledValue
```
public java.math.BigInteger unscaledValue()
```
 Returns a BigInteger whose value is the unscaled value of this Decimal. (Computes (this * 10this.scale()).)
 
 Returns:
 
 the unscaled value of this Decimal.
 - floatValue
```
public float floatValue()
```
 Converts this Decimal to a float.
 
 Specified by:
 
 floatValue in class java.lang.Number
 
 Returns:
 
 this Decimal converted to a float.
 
 See Also:
 
 BigDecimal.floatValue()
 - doubleValue
```
public double doubleValue()
```
 Converts this Decimal to a double.
 
 Specified by:
 
 doubleValue in class java.lang.Number
 
 Returns:
 
 this Decimal converted to a double.
 
 See Also:
 
 BigDecimal.doubleValue()
 - intValue
```
public int intValue()
```
 Converts this Decimal to an int.
 
 Specified by:
 
 intValue in class java.lang.Number
 
 Returns:
 
 this Decimal converted to an int.
 
 See Also:
 
 BigDecimal.intValue()
 - intValueExact
```
public int intValueExact()
```
 Converts this Decimal to an int, checking for lost information. If this Decimal has a nonzero fractional part or is out of the possible range for an int result then an ArithmeticException is thrown.
 
 Returns:
 
 this Decimal converted to an int.
 
 Throws:
 
 java.lang.ArithmeticException - if this has a nonzero fractional part, or will not fit in an int.
 - longValue
```
public long longValue()
```
 Converts this Decimal to a long.
 
 Specified by:
 
 longValue in class java.lang.Number
 
 Returns:
 
 this Decimal converted to a long.
 
 See Also:
 
 BigDecimal.longValue()
 - longValueExact
```
public long longValueExact()
```
 Converts this Decimal to a long, checking for lost information. If this Decimal has a nonzero fractional part or is out of the possible range for a long result then an ArithmeticException is thrown.
 
 Returns:
 
 this Decimal converted to a long.
 
 Throws:
 
 java.lang.ArithmeticException - if this has a nonzero fractional part, or will not fit in a long.
 - toBigDecimal
```
public java.math.BigDecimal toBigDecimal()
```
 Converts this Decimal to a BigDecimal.
 
 Returns:
 
 this Decimal converted to a BigDecimal.
 - toBigInteger
```
public java.math.BigInteger toBigInteger()
```
 Converts this Decimal to a BigInteger.
 
 Returns:
 
 this Decimal> converted to a BigInteger.
 
 See Also:
 
 BigDecimal.toBigInteger()
 - toBigIntegerExact
```
public java.math.BigInteger toBigIntegerExact()
```
 Converts this Decimal to a BigInteger, checking for lost information. An exception is thrown if this Decimal has a nonzero fractional part.
 
 Returns:
 
 this Decimal converted to a BigInteger.
 
 Throws:
 
 java.lang.ArithmeticException - if this has a nonzero fractional part.
 - isInteger
```
public boolean isInteger()
```
 Returns true if this Decimal is an integer, i.e. x.scale() <= 0.
 
 Returns:
 
 true if this Decimal is an integer
 - compareTo
```
public int compareTo(Decimal val)
```
 Compares this Decimal with the specified Decimal. 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.
 
 Specified by:
 
 compareTo in interface java.lang.Comparable<Decimal>
 
 Parameters:
 
 val - Decimal to which this Decimal is to be compared.
 
 Returns:
 
 -1, 0, or 1 as this Decimal is numerically less than, equal to, or greater than val.
 
 Throws:
 
 java.lang.NullPointerException - if val is null
 - hashCode
```
public int hashCode()
```
 Returns the hash code for this Decimal.
 
 Overrides:
 
 hashCode in class java.lang.Object
 
 Returns:
 
 hash code for this Decimal.
 
 See Also:
 
 equals(Object)
 - equals
```
public boolean equals(java.lang.Object obj)
```
 Compares this Decimal with the specified Object for equality. This method returns true if and only if the obj is Decimal and this.compareTo(obj) == 0 holds (thus 2.0 is equal to 2.00 when compared by this method).
 
 Overrides:
 
 equals in class java.lang.Object
 
 Parameters:
 
 obj - Object to which this Decimal is to be compared.
 
 Returns:
 
 true if and only if the specified Object is a Decimal whose value and scale are equal to this Decimal's.
 
 See Also:
 
 compareTo(com.whitestein.lsps.lang.Decimal), hashCode()
 - toString
```
public java.lang.String toString()
```
 This method is identical to BigDecimal.toString(); only in the case when the scale is in the range [-1, -20], the scale is extended to 0 by adding zeros and only after then the BigDecimal.toString() method is performed.
 The canonical representation of Decimal means that decimals with different notation, but with equal value will always have the same toString representation.
 
 Overrides:
 
 toString in class java.lang.Object
 
 See Also:
 
 BigDecimal.toString()
 - toPlainString
```
public java.lang.String toPlainString()
```
 Returns a string representation of this Decimal without an exponent field.
 
 Returns:
 
 a string representation of this Decimal without an exponent field.
 
 See Also:
 
 BigDecimal.toPlainString()
 - valueOf
```
public static Decimal valueOf(int val)
```
 Translates a int value into a Decimal 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 Decimal values.
 
 Parameters:
 
 val - value of the Decimal.
 
 Returns:
 
 a Decimal whose value is val.
 - valueOf
```
public static Decimal valueOf(long val)
```
 Translates a long value into a Decimal 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 Decimal values.
 
 Parameters:
 
 val - value of the Decimal.
 
 Returns:
 
 a Decimal whose value is val.
 - valueOf
```
public static Decimal valueOf(java.lang.Number number)
```
 Attempts to construct the decimal using a best-fit algorithm:
 - Long, Integer, Short, Byte uses the valueOf(long) method
 - Float uses valueOf(float)
 - Double uses valueOf(double)
 - BigInteger uses Decimal(java.math.BigInteger)
 - BigDecimal uses Decimal(java.math.BigDecimal)
 - Decimal just return the number
 All other numbers are rejected to avoid precision loss.
 Parameters:
 
 number -
 
 Returns:
 
 a Decimal whose value is number
 - valueOf
```
public static Decimal valueOf(double val)
```
 Translates a double into a Decimal, using the double's canonical string representation provided by the Double.toString(double) method.
 Note: This is generally the preferred way to convert a double into a Decimal, as the value returned is equal to that resulting from constructing a Decimal from the result of using Double.toString(double).
 
 Parameters:
 
 val - double to convert to a Decimal.
 
 Returns:
 
 a Decimal whose value is equal to or approximately equal to the value of val.
 
 Throws:
 
 java.lang.NumberFormatException - if val is infinite or NaN.
 - valueOf
```
public static Decimal valueOf(float val)
```
 Translates a float into a Decimal, using the float's canonical string representation provided by the Float.toString(float) method.
 Note: This is generally the preferred way to convert a float into a Decimal, as the value returned is equal to that resulting from constructing a Decimal from the result of using Float.toString(float).
 
 Parameters:
 
 val - float to convert to a Decimal.
 
 Returns:
 
 a Decimal whose value is equal to or approximately equal to the value of val.
 
 Throws:
 
 java.lang.NumberFormatException - if val is infinite or NaN.

Class Decimal

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Number

Methods inherited from class java.lang.Object

Field Detail

ZERO

ONE

MINUS_ONE

Constructor Detail

Decimal

Decimal

Decimal

Decimal

Decimal

Decimal

Method Detail

abs

add

subtract

multiply

divide

divideToIntegralValue

negate

remainder

pow

signum

scale

setScale

precision

unscaledValue

floatValue

doubleValue

intValue

intValueExact

longValue

longValueExact

toBigDecimal

toBigInteger

toBigIntegerExact

isInteger

compareTo

hashCode

equals

toString

toPlainString

valueOf

valueOf

valueOf

valueOf

valueOf