DecimalArithmetic (decimal4j API 1.0.7-SNAPSHOT)

All Known Implementing Classes:

AbstractArithmetic, AbstractCheckedArithmetic, AbstractCheckedScale0fArithmetic, AbstractCheckedScaleNfArithmetic, AbstractUncheckedArithmetic, AbstractUncheckedScale0fArithmetic, AbstractUncheckedScaleNfArithmetic, CheckedScale0fRoundingArithmetic, CheckedScale0fTruncatingArithmetic, CheckedScaleNfRoundingArithmetic, CheckedScaleNfTruncatingArithmetic, UncheckedScale0fRoundingArithmetic, UncheckedScale0fTruncatingArithmetic, UncheckedScaleNfRoundingArithmetic, UncheckedScaleNfTruncatingArithmetic
```
public interface DecimalArithmetic
```
DecimalArithmetic defines the basic primitive operations for Decimal numbers for one particular combination of scale, rounding mode and overflow mode. Primitive here means that Decimal values are simply represented by their underlying unscaled long value. All operations therefore use unscaled longs for Decimal arguments and return longs for Decimal number results.
Application code does not usually need to use DecimalArithmetic directly. It may be appropriate however for very specialized applications with low latency, high frequency or zero garbage requirements. All operations of DecimalArithmetic do not allocate any objects (zero garbage) unless otherwise indicated.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`long`	`abs(long uDecimal)` Returns an unscaled decimal whose value is `abs(uDecimal)`, which is the value itself if `uDecimal>=0` and `-uDecimal` if the given value is negative.
`long`	`add(long uDecimal1, long uDecimal2)` Returns an unscaled decimal whose value is `(uDecimal1 + uDecimal2)`.
`long`	`addLong(long uDecimal, long lValue)` Returns an unscaled decimal whose value is the sum of the specified arguments: `(uDecimal + lValue)`.
`long`	`addUnscaled(long uDecimal, long unscaled, int scale)` Returns an unscaled decimal whose value is `(uDecimal + unscaled * 10^-scale)`.
`long`	`avg(long uDecimal1, long uDecimal2)` Returns an unscaled decimal whose value is the average of `uDecimal1` and `uDecimal2`.
`int`	`compare(long uDecimal1, long uDecimal2)` Compares two unscaled decimal values numerically.
`int`	`compareToUnscaled(long uDecimal, long unscaled, int scale)` Compares two unscaled decimal values numerically.
`DecimalArithmetic`	`deriveArithmetic(int scale)` Derives an arithmetic instance for the specified `scale` using this arithmetic's `rounding mode` and `overflow mode`.
`DecimalArithmetic`	`deriveArithmetic(OverflowMode overflowMode)` Derives an arithmetic instance for the same `scale` as this arithmetic but for the specified `overflowMode`.
`DecimalArithmetic`	`deriveArithmetic(RoundingMode roundingMode)` Derives an arithmetic instance for the same `scale` as this arithmetic but for the specified `roundingMode`.
`DecimalArithmetic`	`deriveArithmetic(RoundingMode roundingMode, OverflowMode overflowMode)` Derives an arithmetic instance for the same `scale` as this arithmetic but for the specified `roundingMode` and `overflowMode`.
`DecimalArithmetic`	`deriveArithmetic(TruncationPolicy truncationPolicy)` Derives an arithmetic instance for the same `scale` as this arithmetic but with rounding and overflow mode specified by the given `truncationPolicy`.
`long`	`divide(long uDecimalDividend, long uDecimalDivisor)` Returns an unscaled decimal whose value is the quotient of the specified arguments: `(uDecimalDividend / uDecimalDivisor)`.
`long`	`divideByLong(long uDecimalDividend, long lDivisor)` Returns an unscaled decimal whose value is `(uDecimalDividend / lDivisor)` where the second argument is a true long value instead of an unscaled decimal.
`long`	`divideByPowerOf10(long uDecimal, int n)` Returns an unscaled decimal whose value is `(uDecimal / 10ⁿ)`.
`long`	`divideByUnscaled(long uDecimal, long unscaled, int scale)` Returns an unscaled decimal whose value is `(uDecimal / (unscaled * 10^-scale))`.
`long`	`fromBigDecimal(BigDecimal value)` Converts the specified `BigDecimal` value to an unscaled decimal.
`long`	`fromBigInteger(BigInteger value)` Converts the specified `BigInteger` value to an unscaled decimal.
`long`	`fromDouble(double value)` Converts the specified double value to an unscaled decimal.
`long`	`fromFloat(float value)` Converts the specified float value to an unscaled decimal.
`long`	`fromLong(long value)` Converts the specified long value to an unscaled decimal.
`long`	`fromUnscaled(long unscaledValue, int scale)` Converts the specified unscaled decimal with the given scale to another unscaled decimal of the scale of this arithmetic.
`OverflowMode`	`getOverflowMode()` Returns the overflow mode applied to operations of this `DecimalArithmetic` object if an overflow occurs.
`RoundingMode`	`getRoundingMode()` Returns the rounding mode applied to operations of this `DecimalArithmetic` object if rounding is necessary.
`int`	`getScale()` Returns the scale `f` applied to all unscaled decimal values passed to and returned by this `DecimalArithmetic`.
`ScaleMetrics`	`getScaleMetrics()` Returns the scale metrics associated with this decimal arithmetic object.
`TruncationPolicy`	`getTruncationPolicy()` Returns the truncation policy defining how to handle truncation due to overflow or rounding.
`long`	`invert(long uDecimal)` Returns an unscaled decimal whose value is the inverse of the argument: `1/uDecimal`.
`long`	`multiply(long uDecimal1, long uDecimal2)` Returns an unscaled decimal whose value is the product of the specified arguments: `(uDecimal1 * uDecimal2)`.
`long`	`multiplyByLong(long uDecimal, long lValue)` Returns an unscaled decimal whose value is `(uDecimal * lValue)` where the second argument is a true long value instead of an unscaled decimal.
`long`	`multiplyByPowerOf10(long uDecimal, int n)` Returns an unscaled decimal whose value is `(uDecimal * 10ⁿ)`.
`long`	`multiplyByUnscaled(long uDecimal, long unscaled, int scale)` Returns an unscaled decimal whose value is `(uDecimal * unscaled * 10^-scale)`.
`long`	`negate(long uDecimal)` Returns an unscaled decimal whose value is `-uDecimal`.
`long`	`one()` Returns the unscaled decimal for the decimal value `1`.
`long`	`parse(CharSequence value, int start, int end)` Translates the string representation of a `Decimal` into an unscaled Decimal.
`long`	`parse(String value)` Translates the string representation of a `Decimal` into an unscaled Decimal.
`long`	`pow(long uDecimalBase, int exponent)` Returns an unscaled decimal whose value is `(uDecimalBase^exponent)`.
`long`	`round(long uDecimal, int precision)` Returns an unscaled decimal whose value is rounded to the specified `precision` using the `rounding mode` of this arithmetic.
`long`	`shiftLeft(long uDecimal, int n)` Returns an unscaled decimal whose value is `(uDecimal << n)`.
`long`	`shiftRight(long uDecimal, int n)` Returns an unscaled decimal whose value is `(uDecimal >> n)`.
`int`	`signum(long uDecimal)` Returns the signum function of the specified unscaled decimal.
`long`	`sqrt(long uDecimal)` Returns an unscaled decimal whose value is the square root of the specified argument: `sqrt(uDecimal)`.
`long`	`square(long uDecimal)` Returns an unscaled decimal whose value is the square of the specified argument: `uDecimal²`.
`long`	`subtract(long uDecimalMinuend, long uDecimalSubtrahend)` Returns an unscaled decimal whose value is `(uDecimalMinuend - uDecimalSubtrahend)`.
`long`	`subtractLong(long uDecimal, long lValue)` Returns an unscaled decimal whose value is the difference of the specified arguments: `(uDecimal - lValue)` .
`long`	`subtractUnscaled(long uDecimal, long unscaled, int scale)` Returns an unscaled decimal whose value is `(uDecimal - unscaled * 10^-scale)`.
`BigDecimal`	`toBigDecimal(long uDecimal)` Converts the specified unscaled decimal value into a `BigDecimal` value using this arithmetic's `scale` for the result value.
`BigDecimal`	`toBigDecimal(long uDecimal, int scale)` Converts the specified unscaled decimal value into a `BigDecimal` value using the specified `scale` for the result value.
`double`	`toDouble(long uDecimal)` Converts the specified unscaled decimal value into a double value and returns it.
`float`	`toFloat(long uDecimal)` Converts the specified unscaled decimal value into a float value and returns it.
`long`	`toLong(long uDecimal)` Converts the specified unscaled decimal value into a long value and returns it.
`String`	`toString(long uDecimal)` Converts the specified unscaled decimal value into a `String` and returns it.
`void`	`toString(long uDecimal, Appendable appendable)` Converts the specified unscaled decimal value into a `String` and appends the string to the `appendable`.
`long`	`toUnscaled(long uDecimal, int scale)` Converts the specified unscaled decimal value into an unscaled value of the given scale.

- Method Detail
  - getScale
```
int getScale()
```
    Returns the scale f applied to all unscaled decimal values passed to and returned by this DecimalArithmetic. Corresponds to the number of digits to the right of the decimal point (cannot be negative).
    A given Decimal value multiplied with 10^f results in an unscaled long value. Conversely, a Decimal value d can be computed from the unscaled value u as d = u*10^-f.
    
    Returns:
    
    the non-negative scale f applied to unscaled decimal values within this DecimalArithmetic object
    
    See Also:
    
    ScaleMetrics.getScale()
  - getScaleMetrics
```
ScaleMetrics getScaleMetrics()
```
    Returns the scale metrics associated with this decimal arithmetic object.
    
    Returns:
    
    the scale metrics
  - getRoundingMode
```
RoundingMode getRoundingMode()
```
    Returns the rounding mode applied to operations of this DecimalArithmetic object if rounding is necessary.
    
    Returns:
    
    the rounding mode applied to operations of this DecimalArithmetic object if rounding is necessary
  - getOverflowMode
```
OverflowMode getOverflowMode()
```
    Returns the overflow mode applied to operations of this DecimalArithmetic object if an overflow occurs. The overflow mode defines whether an operation should throw an exception if an overflow occurs.
    
    Returns:
    
    the overflow mode applied to operations of this DecimalArithmetic object if an overflow occurs
  - getTruncationPolicy
```
TruncationPolicy getTruncationPolicy()
```
    Returns the truncation policy defining how to handle truncation due to overflow or rounding. The TruncationPolicy is defined by the overflow mode and the rounding mode.
    
    Returns:
    
    the truncation policy defining how this DecimalArithmetic handles truncation
  - deriveArithmetic
```
DecimalArithmetic deriveArithmetic(int scale)
```
    Derives an arithmetic instance for the specified scale using this arithmetic's rounding mode and overflow mode.
    
    Parameters:
    
    scale - the scale for the new arithmetic; must be in [0,18] both ends inclusive
    
    Returns:
    
    an arithmetic instance with the given scale and this arithmetic's rounding and overflow mode
    
    Throws:
    
    IllegalArgumentException - if scale is not in [0, 18]
    
    See Also:
    
    Scales.getScaleMetrics(int), ScaleMetrics.getArithmetic(RoundingMode), ScaleMetrics.getArithmetic(TruncationPolicy)
  - deriveArithmetic
```
DecimalArithmetic deriveArithmetic(RoundingMode roundingMode)
```
    Derives an arithmetic instance for the same scale as this arithmetic but for the specified roundingMode. The returned arithmetic uses the same overflow mode as this arithmetic.
    
    Parameters:
    
    roundingMode - the rounding mode for the new arithmetic
    
    Returns:
    
    an arithmetic instance with the given rounding mode and this arithmetic's scale and overflow mode
    
    Throws:
    
    NullPointerException - if rounding mode is null
  - deriveArithmetic
```
DecimalArithmetic deriveArithmetic(RoundingMode roundingMode,
                                   OverflowMode overflowMode)
```
    Derives an arithmetic instance for the same scale as this arithmetic but for the specified roundingMode and overflowMode.
    
    Parameters:
    
    roundingMode - the rounding mode for the new arithmetic
    
    overflowMode - the overflow mode for the new arithmetic
    
    Returns:
    
    an arithmetic instance with the given rounding and overflow mode and this arithmetic's scale
    
    Throws:
    
    NullPointerException - if any of the arguments is null
  - deriveArithmetic
```
DecimalArithmetic deriveArithmetic(OverflowMode overflowMode)
```
    Derives an arithmetic instance for the same scale as this arithmetic but for the specified overflowMode. The returned arithmetic uses the same rounding mode as this arithmetic.
    
    Parameters:
    
    overflowMode - the overflow mode for the new arithmetic
    
    Returns:
    
    an arithmetic instance with the given overflow mode and this arithmetic's scale and rounding mode
    
    Throws:
    
    NullPointerException - if overflow mode is null
  - deriveArithmetic
```
DecimalArithmetic deriveArithmetic(TruncationPolicy truncationPolicy)
```
    Derives an arithmetic instance for the same scale as this arithmetic but with rounding and overflow mode specified by the given truncationPolicy.
    
    Parameters:
    
    truncationPolicy - the truncation policy specifying rounding and overflow mode for the new arithmetic
    
    Returns:
    
    an arithmetic instance with rounding and overflow mode specified by the truncation policy using this arithmetic's scale
    
    Throws:
    
    NullPointerException - if truncation policy is null
  - one
```
long one()
```
    Returns the unscaled decimal for the decimal value 1. One is the value 10^scale which is also the multiplier used to get the unscaled decimal from the true decimal value.
    
    Returns:
    
    the unscaled decimal representing the decimal value 1
  - signum
```
int signum(long uDecimal)
```
    Returns the signum function of the specified unscaled decimal.
    
    Parameters:
    
    uDecimal - the unscaled decimal
    
    Returns:
    
    -1, 0, or 1 as the value of the specified unscaled decimal is negative, zero, or positive.
  - compare
```
int compare(long uDecimal1,
            long uDecimal2)
```
    Compares two unscaled decimal values numerically.
    
    Parameters:
    
    uDecimal1 - the first unscaled decimal to compare
    
    uDecimal2 - the second unscaled decimal to compare
    
    Returns:
    
    the value 0 if unscaled1 == unscaled2; a value less than 0 if unscaled1 < unscaled2; and a value greater than 0 if unscaled1 > unscaled2
  - compareToUnscaled
```
int compareToUnscaled(long uDecimal,
                      long unscaled,
                      int scale)
```
    Compares two unscaled decimal values numerically. Note that scale of the first operand is determined by this arithmetic's scale whereas the scale of the second unscaled value is explicitly specified by the scale argument.
    
    Parameters:
    
    uDecimal - the first unscaled decimal to compare
    
    unscaled - the second unscaled decimal to compare
    
    scale - the scale of unscaled
    
    Returns:
    
    the value 0 if unscaled1 == unscaled2; a value less than 0 if unscaled1 < unscaled2; and a value greater than 0 if unscaled1 > unscaled2
  - add
```
long add(long uDecimal1,
         long uDecimal2)
```
    Returns an unscaled decimal whose value is (uDecimal1 + uDecimal2).
    
    Parameters:
    
    uDecimal1 - first unscaled decimal value to be added
    
    uDecimal2 - second unscaled decimal value to be added
    
    Returns:
    
    uDecimal1 + uDecimal2
    
    Throws:
    
    ArithmeticException - if an overflow occurs and the overflow mode is set to throw an exception
  - addLong
```
long addLong(long uDecimal,
             long lValue)
```
    Returns an unscaled decimal whose value is the sum of the specified arguments: (uDecimal + lValue).
    Mathematically the method calculates (uDecimal + lValue * 10^scale) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - unscaled decimal value to be added
    
    lValue - long value to be added
    
    Returns:
    
    (uDecimal + lValue * 10^scale)
    
    Throws:
    
    ArithmeticException - if an overflow occurs and the overflow mode is set to throw an exception
  - addUnscaled
```
long addUnscaled(long uDecimal,
                 long unscaled,
                 int scale)
```
    Returns an unscaled decimal whose value is (uDecimal + unscaled * 10^-scale). If rounding must be performed, this arithmetic's rounding mode is applied. Note that scale of the first operand is determined by this arithmetic's scale whereas the scale of the second unscaled value is explicitly specified by the scale argument.
    Mathematically the method calculates round(uDecimal + lValue * 10^{-scale + s}) where s refers to this arithetic's scale. The method avoids information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - unscaled decimal value to be added to
    
    unscaled - unscaled value to add
    
    scale - scale associated with the unscaled value
    
    Returns:
    
    round(uDecimal + unscaled * 10^-scale)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - subtract
```
long subtract(long uDecimalMinuend,
              long uDecimalSubtrahend)
```
    Returns an unscaled decimal whose value is (uDecimalMinuend - uDecimalSubtrahend).
    
    Parameters:
    
    uDecimalMinuend - unscaled decimal value to subtract from
    
    uDecimalSubtrahend - unscaled decimal value to subtract from the minuend
    
    Returns:
    
    uDecimalMinuend - uDecimalSubtrahend
    
    Throws:
    
    ArithmeticException - if an overflow occurs and the overflow mode is set to throw an exception
  - subtractLong
```
long subtractLong(long uDecimal,
                  long lValue)
```
    Returns an unscaled decimal whose value is the difference of the specified arguments: (uDecimal - lValue) .
    Mathematically the method calculates (uDecimal - lValue * 10^scale) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - unscaled decimal value to subtract from
    
    lValue - long value to subtract
    
    Returns:
    
    (uDecimal - lValue * 10^scale)
    
    Throws:
    
    ArithmeticException - if an overflow occurs and the overflow mode is set to throw an exception
  - subtractUnscaled
```
long subtractUnscaled(long uDecimal,
                      long unscaled,
                      int scale)
```
    Returns an unscaled decimal whose value is (uDecimal - unscaled * 10^-scale). If rounding must be performed, this arithmetic's rounding mode is applied. Note that scale of the first operand is determined by this arithmetic's scale whereas the scale of the second unscaled value is explicitly specified by the scale argument.
    Mathematically the method calculates round(uDecimal - lValue * 10^{-scale + s}) where s refers to this arithetic's scale. The method avoids information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - unscaled decimal value to subtract from
    
    unscaled - unscaled value to subtract
    
    scale - scale associated with the unscaled value
    
    Returns:
    
    round(uDecimal - unscaled * 10^-scale) as unscaled decimal
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - multiply
```
long multiply(long uDecimal1,
              long uDecimal2)
```
    Returns an unscaled decimal whose value is the product of the specified arguments: (uDecimal1 * uDecimal2). If rounding must be performed, this arithmetic's rounding mode is applied.
    Mathematically the method calculates round((uDecimal1 * uDecimal2) * 10^-scale) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal1 - first unscaled decimal value to be multiplied
    
    uDecimal2 - second unscaled decimal value to be multiplied
    
    Returns:
    
    round(uDecimal1 * uDecimal2)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - multiplyByLong
```
long multiplyByLong(long uDecimal,
                    long lValue)
```
    Returns an unscaled decimal whose value is (uDecimal * lValue) where the second argument is a true long value instead of an unscaled decimal.
    
    Parameters:
    
    uDecimal - unscaled decimal value to be multiplied
    
    lValue - long value to be multiplied
    
    Returns:
    
    uDecimal * lValue
    
    Throws:
    
    ArithmeticException - if an overflow occurs and the overflow mode is set to throw an exception
  - multiplyByUnscaled
```
long multiplyByUnscaled(long uDecimal,
                        long unscaled,
                        int scale)
```
    Returns an unscaled decimal whose value is (uDecimal * unscaled * 10^-scale). If rounding must be performed, this arithmetic's rounding mode is applied. Note that scale of the first operand is determined by this arithmetic's scale whereas the scale of the second unscaled value is explicitly specified by the scale argument.
    Mathematically the method calculates round((uDecimal * unscaled) * 10^-scale) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - unscaled decimal value to be multiplied
    
    unscaled - unscaled value to be multiplied
    
    scale - scale associated with the unscaled value
    
    Returns:
    
    round(uDecimal * (unscaled * 10^-scale))
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - multiplyByPowerOf10
```
long multiplyByPowerOf10(long uDecimal,
                         int n)
```
    Returns an unscaled decimal whose value is (uDecimal * 10ⁿ).
    The power, n, may be negative, in which case this method performs a division by a power of ten. If rounding must be performed (for negative n), this arithmetic's rounding mode is applied.
    
    Parameters:
    
    uDecimal - value to be multiplied
    
    n - the power of ten
    
    Returns:
    
    round(uDecimal × 10ⁿ)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - divide
```
long divide(long uDecimalDividend,
            long uDecimalDivisor)
```
    Returns an unscaled decimal whose value is the quotient of the specified arguments: (uDecimalDividend / uDecimalDivisor). If rounding must be performed, this arithmetic's rounding mode is applied.
    Mathematically the method calculates round((uDecimalDividend * 10^scale) / uDecimalDivisor) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimalDividend - value to be divided.
    
    uDecimalDivisor - value by which the dividend is to be divided.
    
    Returns:
    
    round(uDecimalDividend / uDecimalDivisor)
    
    Throws:
    
    ArithmeticException - if uDecimalDividend is zero, if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - divideByLong
```
long divideByLong(long uDecimalDividend,
                  long lDivisor)
```
    Returns an unscaled decimal whose value is (uDecimalDividend / lDivisor) where the second argument is a true long value instead of an unscaled decimal. If rounding must be performed, this arithmetic's rounding mode is applied.
    
    Parameters:
    
    uDecimalDividend - value to be divided.
    
    lDivisor - long value by which the dividend is to be divided.
    
    Returns:
    
    round(uDecimalDividend / lDivisor)
    
    Throws:
    
    ArithmeticException - if uDecimalDividend is zero, if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - divideByUnscaled
```
long divideByUnscaled(long uDecimal,
                      long unscaled,
                      int scale)
```
    Returns an unscaled decimal whose value is (uDecimal / (unscaled * 10^-scale)). If rounding must be performed, this arithmetic's rounding mode is applied. Note that scale of the first operand is determined by this arithmetic's scale whereas the scale of the second unscaled value is explicitly specified by the scale argument.
    Mathematically the method calculates round((uDecimal * 10^scale) / unscaled) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - value to be divided.
    
    unscaled - unscaled value by which the dividend is to be divided.
    
    scale - scale associated with the unscaled value
    
    Returns:
    
    round(uDecimal / (unscaled * 10^-scale))
    
    Throws:
    
    ArithmeticException - if uDecimal is zero, if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - divideByPowerOf10
```
long divideByPowerOf10(long uDecimal,
                       int n)
```
    Returns an unscaled decimal whose value is (uDecimal / 10ⁿ). If rounding must be performed, this arithmetic's rounding mode is applied.
    The power, n, may be negative, in which case this method performs a multiplication by a power of ten.
    
    Parameters:
    
    uDecimal - value to be divided.
    
    n - the power of ten
    
    Returns:
    
    round(uDecimal / 10ⁿ)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - avg
```
long avg(long uDecimal1,
         long uDecimal2)
```
    Returns an unscaled decimal whose value is the average of uDecimal1 and uDecimal2. The method is much more efficient than an addition and subsequent long division and is guaranteed not to overflow. If rounding must be performed, this arithmetic's rounding mode is applied.
    
    Parameters:
    
    uDecimal1 - the first unscaled decimal value to average
    
    uDecimal2 - the second unscaled decimal value to average
    
    Returns:
    
    round((uDecimal1 + uDecimal2) / 2)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - abs
```
long abs(long uDecimal)
```
    Returns an unscaled decimal whose value is abs(uDecimal), which is the value itself if uDecimal>=0 and -uDecimal if the given value is negative.
    
    Parameters:
    
    uDecimal - the unscaled decimal value
    
    Returns:
    
    abs(uDecimal)
    
    Throws:
    
    ArithmeticException - if an overflow occurs and the overflow mode is set to throw an exception
  - negate
```
long negate(long uDecimal)
```
    Returns an unscaled decimal whose value is -uDecimal.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to negate
    
    Returns:
    
    -uDecimal
    
    Throws:
    
    ArithmeticException - if an overflow occurs and the overflow mode is set to throw an exception
  - invert
```
long invert(long uDecimal)
```
    Returns an unscaled decimal whose value is the inverse of the argument: 1/uDecimal. If rounding must be performed, this arithmetic's rounding mode is applied.
    Mathematically the method calculates round((10^scale * 10^scale) / uDecimalDivisor) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to invert
    
    Returns:
    
    round(1/uDecimal)
    
    Throws:
    
    ArithmeticException - if uDecimal is zero, if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - square
```
long square(long uDecimal)
```
    Returns an unscaled decimal whose value is the square of the specified argument: uDecimal². If rounding must be performed, this arithmetic's rounding mode is applied.
    Mathematically the method calculates round((uDecimal * uDecimal) * 10^-scale) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to be squared
    
    Returns:
    
    round(uDecimal * uDecimal)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - sqrt
```
long sqrt(long uDecimal)
```
    Returns an unscaled decimal whose value is the square root of the specified argument: sqrt(uDecimal). If rounding must be performed, this arithmetic's rounding mode is applied.
    Mathematically the method calculates round(sqrt(uDecimal * 10^scale)) avoiding information loss due to overflow of intermediary results.
    
    Parameters:
    
    uDecimal - the unscaled decimal value
    
    Returns:
    
    round(sqrt(uDecimal))
    
    Throws:
    
    ArithmeticException - if uDecimal is negative or if rounding mode is UNNECESSARY and rounding is necessary
  - pow
```
long pow(long uDecimalBase,
         int exponent)
```
    Returns an unscaled decimal whose value is (uDecimalBase^exponent). Note that exponent is an integer rather than a decimal. If rounding must be performed, this arithmetic's rounding mode is applied.
    The current implementation uses the core algorithm defined in ANSI standard X3.274-1996. For exponent >= 0, the returned numerical value is within 1 ULP of the exact numerical value; the result is actually exact for all rounding modes other than HALF_UP, HALF_EVEN and HALF_DOWN. No precision is guaranteed for exponent < 0 but the result is usually exact up to 10-20 ULP.
    Properties of the X3.274-1996 algorithm are:
    - An IllegalArgumentException is thrown if abs(n) > 999999999
    - if exponent is zero, one is returned even if uDecimalBase is zero, otherwise
      
      if exponent is positive, the result is calculated via the repeated squaring technique into a single accumulator
      
      if exponent is negative, the result is calculated as if exponent were positive; this value is then divided into one
      
      The final value from either the positive or negative case is then rounded using this arithmetic's rounding mode
    Note: this operation is not strictly garbage free since internally, two ThreadLocal objects are used to calculate the result. The ThreadLocal values may become garbage if the thread becomes garbage.
    Parameters:
    
    uDecimalBase - the unscaled decimal base value
    
    exponent - exponent to which uDecimalBase is to be raised.
    
    Returns:
    
    uDecimalBase^exponent
    
    Throws:
    
    IllegalArgumentException - if abs(exponent) > 999999999
    
    ArithmeticException - if uDecimalBase==0 and exponent is negative. (This would cause a division by zero.), if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - shiftLeft
```
long shiftLeft(long uDecimal,
               int n)
```
    Returns an unscaled decimal whose value is (uDecimal << n). The shift distance, n, may be negative, in which case this method performs a right shift. The result is equal to round(uDecimal * 2ⁿ) using this arithmetic's rounding mode if rounding is necessary.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to shift
    
    n - shift distance, in bits.
    
    Returns:
    
    round(uDecimal << n)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
    
    See Also:
    
    shiftRight(long, int)
  - shiftRight
```
long shiftRight(long uDecimal,
                int n)
```
    Returns an unscaled decimal whose value is (uDecimal >> n). The shift distance, n, may be negative, in which case this method performs a left shift. The result is equal to round(uDecimal / 2ⁿ) using this arithmetic's rounding mode if rounding is necessary.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to shift
    
    n - shift distance, in bits.
    
    Returns:
    
    round(uDecimal >> n)
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
    
    See Also:
    
    shiftLeft(long, int)
  - round
```
long round(long uDecimal,
           int precision)
```
    Returns an unscaled decimal whose value is rounded to the specified precision using the rounding mode of this arithmetic.
    Note that this method does not change the scale of the value --- extra digits are simply zeroised.
    Examples and special cases:
    - precision = 0
      value is rounded to an integer value
    - precision = 2
      value is rounded to the second digit after the decimal point
    - precision = -3
      value is rounded to the thousands
    - precision ≥ scale
      values is returned unchanged
    - precision < scale - 18
      IllegalArgumentException is thrown
    Parameters:
    
    uDecimal - the unscaled decimal value to round
    
    precision - the precision to use for the rounding, for instance 2 to round to the second digit after the decimal point; must be at least (scale - 18)
    
    Returns:
    
    an unsigned decimal rounded to the given precision
    
    Throws:
    
    IllegalArgumentException - if precision < scale - 18
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary or if an overflow occurs and the overflow mode is set to throw an exception
  - fromLong
```
long fromLong(long value)
```
    Converts the specified long value to an unscaled decimal. An exception is thrown if the specified value is too large to be represented as a Decimal of this arithmetic's scale.
    
    Parameters:
    
    value - the value to convert
    
    Returns:
    
    the unscaled decimal representing the same value as the given long value
    
    Throws:
    
    IllegalArgumentException - if value is too large to be represented as a Decimal with the scale of this arithmetic
  - fromFloat
```
long fromFloat(float value)
```
    Converts the specified float value to an unscaled decimal. An exception is thrown if the specified value is too large to be represented as a Decimal of this arithmetic's scale.
    
    Parameters:
    
    value - the value to convert
    
    Returns:
    
    the unscaled decimal representing the same value as the given float value
    
    Throws:
    
    IllegalArgumentException - if value is NaN or infinite or if the magnitude is too large for the float to be represented as a Decimal with the scale of this arithmetic
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - fromDouble
```
long fromDouble(double value)
```
    Converts the specified double value to an unscaled decimal. An exception is thrown if the specified value is too large to be represented as a Decimal of this arithmetic's scale.
    
    Parameters:
    
    value - the value to convert
    
    Returns:
    
    the unscaled decimal representing the same value as the given double value
    
    Throws:
    
    IllegalArgumentException - if value is NaN or infinite or if the magnitude is too large for the double to be represented as a Decimal with the scale of this arithmetic
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - fromBigInteger
```
long fromBigInteger(BigInteger value)
```
    Converts the specified BigInteger value to an unscaled decimal. An exception is thrown if the specified value is too large to be represented as a Decimal of this arithmetic's scale.
    
    Parameters:
    
    value - the value to convert
    
    Returns:
    
    the unscaled decimal representing the same value as the given big integer value
    
    Throws:
    
    IllegalArgumentException - if value is too large to be represented as a Decimal with the scale of this arithmetic
  - fromBigDecimal
```
long fromBigDecimal(BigDecimal value)
```
    Converts the specified BigDecimal value to an unscaled decimal. An exception is thrown if the specified value is too large to be represented as a Decimal of this arithmetic's scale.
    Note: this operation is not garbage free, meaning that new temporary objects may be allocated during the conversion.
    
    Parameters:
    
    value - the value to convert
    
    Returns:
    
    the unscaled decimal representing the same value as the given big decimal value
    
    Throws:
    
    IllegalArgumentException - if value is too large to be represented as a Decimal with the scale of this arithmetic
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - fromUnscaled
```
long fromUnscaled(long unscaledValue,
                  int scale)
```
    Converts the specified unscaled decimal with the given scale to another unscaled decimal of the scale of this arithmetic.
    
    Parameters:
    
    unscaledValue - the unscaled decimal value to convert
    
    scale - the scale associated with unscaledValue
    
    Returns:
    
    the unscaled decimal representing the same value as the given unscaled decimal with the new scale defined by this arithmetic
    
    Throws:
    
    IllegalArgumentException - if the unscaled value with the specified scale is too large to be represented as a Decimal with the scale of this arithmetic
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - parse
```
long parse(String value)
```
    Translates the string representation of a Decimal into an unscaled Decimal. 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.
    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. If the fraction contains more digits than this arithmetic's scale, the value is rounded using the arithmetic's rounding mode. An exception is thrown if the value is too large to be represented as a Decimal of this arithmetic's scale.
    
    Parameters:
    
    value - a String containing the decimal value representation to be parsed
    
    Returns:
    
    the decimal as unscaled long value
    
    Throws:
    
    NumberFormatException - if value does not represent a valid Decimal or if the value is too large to be represented as a Decimal with the scale of this arithmetic
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - parse
```
long parse(CharSequence value,
           int start,
           int end)
```
    Translates the string representation of a Decimal into an unscaled Decimal. 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.
    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. If the fraction contains more digits than this arithmetic's scale, the value is rounded using the arithmetic's rounding mode. An exception is thrown if the value is too large to be represented as a Decimal of this arithmetic's scale.
    
    Parameters:
    
    value - a character sequence such as a String containing the decimal value representation to be parsed
    
    start - the start index to read characters in value, inclusive
    
    end - the end index where to stop reading in characters in value, exclusive
    
    Returns:
    
    the decimal as unscaled long value
    
    Throws:
    
    IndexOutOfBoundsException - if start < 0 or end > value.length()
    
    NumberFormatException - if value does not represent a valid Decimal or if the value is too large to be represented as a Decimal with the scale of this arithmetic
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - toLong
```
long toLong(long uDecimal)
```
    Converts the specified unscaled decimal value into a long value and returns it. The arithmetic's rounding mode is applied if rounding is necessary.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into a long value
    
    Returns:
    
    the uDecimal value converted into a long value, possibly rounded or truncated
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - toUnscaled
```
long toUnscaled(long uDecimal,
                int scale)
```
    Converts the specified unscaled decimal value into an unscaled value of the given scale. The arithmetic's rounding mode is applied if rounding is necessary.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into an unscaled value of the specified scale
    
    scale - the target scale for the result value
    
    Returns:
    
    the uDecimal value converted into an unscaled value of the specified scale, possibly rounded or truncated
    
    Throws:
    
    IllegalArgumentException - if the unscaled value with this arithmetic's scale is too large to be represented as an unscaled decimal with the specified scale
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - toFloat
```
float toFloat(long uDecimal)
```
    Converts the specified unscaled decimal value into a float value and returns it. The arithmetic's rounding mode is applied if rounding is necessary.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into a float value
    
    Returns:
    
    the uDecimal value converted into a float value, possibly rounded or truncated
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - toDouble
```
double toDouble(long uDecimal)
```
    Converts the specified unscaled decimal value into a double value and returns it. The arithmetic's rounding mode is applied if rounding is necessary.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into a double value
    
    Returns:
    
    the uDecimal value converted into a double value, possibly rounded or truncated
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - toBigDecimal
```
BigDecimal toBigDecimal(long uDecimal)
```
    Converts the specified unscaled decimal value into a BigDecimal value using this arithmetic's scale for the result value.
    Note: this operation is not strictly garbage free since the result value is usually allocated; however no temporary objects other than the result are allocated during the conversion.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into a BigDecimal value
    
    Returns:
    
    the uDecimal value converted into a BigDecimal value
  - toBigDecimal
```
BigDecimal toBigDecimal(long uDecimal,
                        int scale)
```
    Converts the specified unscaled decimal value into a BigDecimal value using the specified scale for the result value. The arithmetic's rounding mode is applied if rounding is necessary.
    Note: this operation is not garbage free since the result value is usually allocated and also temporary objects may be allocated during the conversion. Note however that temporary objects are only allocated if the unscaled value of the result exceeds the range of a long value.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into a BigDecimal value
    
    scale - the scale to use for the resulting BigDecimal value
    
    Returns:
    
    the uDecimal value converted into a BigDecimal value, possibly rounded or truncated
    
    Throws:
    
    ArithmeticException - if rounding mode is UNNECESSARY and rounding is necessary
  - toString
```
String toString(long uDecimal)
```
    Converts the specified unscaled decimal value into a String and returns it. If the scale is zero, the conversion is identical to Long.toString(long). For all other scales a value with exactly scale fraction digits is returned even if some trailing fraction digits are zero.
    Note: this operation is not strictly garbage free since the result value is allocated; however no temporary objects other than the result are allocated during the conversion (internally a ThreadLocal StringBuilder object is used to construct the string value, which may become garbage if the thread becomes garbage).
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into a String
    
    Returns:
    
    the uDecimal value as into a String
  - toString
```
void toString(long uDecimal,
              Appendable appendable)
       throws IOException
```
    Converts the specified unscaled decimal value into a String and appends the string to the appendable.
    If the scale is zero, the conversion into a string is identical to Long.toString(long). For all other scales a string value with exactly scale fraction digits is created even if some trailing fraction digits are zero.
    Note: this operation is not strictly garbage free since internally, a ThreadLocal string builder is used to construct the string. The ThreadLocal value may become garbage if the thread becomes garbage.
    
    Parameters:
    
    uDecimal - the unscaled decimal value to convert into a String
    
    appendable - the appendable to which the string representation of the unscaled decimal value is to be appended
    
    Throws:
    
    IOException - If an I/O error occurs when appending to appendable

Interface DecimalArithmetic

Method Summary

Method Detail

getScale

getScaleMetrics

getRoundingMode

getOverflowMode

getTruncationPolicy

deriveArithmetic

deriveArithmetic

deriveArithmetic

deriveArithmetic

deriveArithmetic

one

signum

compare

compareToUnscaled

add

addLong

addUnscaled

subtract

subtractLong

subtractUnscaled

multiply

multiplyByLong

multiplyByUnscaled

multiplyByPowerOf10

divide

divideByLong

divideByUnscaled

divideByPowerOf10

avg

abs

negate

invert

square

sqrt

pow

shiftLeft

shiftRight

round

fromLong

fromFloat

fromDouble

fromBigInteger

fromBigDecimal

fromUnscaled

parse

parse

toLong

toUnscaled

toFloat

toDouble

toBigDecimal

toBigDecimal

toString

toString