CheckedScale0fRoundingArithmetic (decimal4j API 1.0.7-SNAPSHOT)

java.lang.Object
- org.decimal4j.arithmetic.AbstractArithmetic
- - org.decimal4j.arithmetic.AbstractCheckedArithmetic
  - - org.decimal4j.arithmetic.AbstractCheckedScale0fArithmetic
    - - org.decimal4j.arithmetic.CheckedScale0fRoundingArithmetic

All Implemented Interfaces:

DecimalArithmetic
```
public final class CheckedScale0fRoundingArithmetic
extends AbstractCheckedScale0fArithmetic
```
Arithmetic implementation with rounding and overflow check for the special case with Scale0f, that is, for longs. An exception is thrown if an operation leads to an overflow.

Constructor Summary

Constructors
Constructor and Description
`CheckedScale0fRoundingArithmetic(DecimalRounding rounding)` Constructor for decimal arithmetic with the given rounding.
`CheckedScale0fRoundingArithmetic(RoundingMode roundingMode)` Constructor for decimal arithmetic with the given rounding.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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`.
`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`	`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`	`fromUnscaled(long unscaledValue, int scale)` Converts the specified unscaled decimal with the given scale to another unscaled decimal of the scale of this arithmetic.
`RoundingMode`	`getRoundingMode()` Returns the rounding mode applied to operations of this `DecimalArithmetic` object if rounding is necessary.
`CheckedRounding`	`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`	`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`	`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)`.
`long`	`sqrt(long uDecimal)` Returns an unscaled decimal whose value is the square root of the specified argument: `sqrt(uDecimal)`.
`long`	`subtractUnscaled(long uDecimal, long unscaled, int scale)` Returns an unscaled decimal whose value is `(uDecimal - unscaled * 10^-scale)`.
`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`	`toUnscaled(long uDecimal, int scale)` Converts the specified unscaled decimal value into an unscaled value of the given scale.

Methods inherited from class org.decimal4j.arithmetic.AbstractCheckedScale0fArithmetic
addLong, fromLong, getScale, getScaleMetrics, multiply, one, square, subtractLong, toLong, toString, toString

Methods inherited from class org.decimal4j.arithmetic.AbstractCheckedArithmetic
abs, add, getOverflowMode, multiplyByLong, negate, subtract

Methods inherited from class org.decimal4j.arithmetic.AbstractArithmetic
compare, compareToUnscaled, deriveArithmetic, deriveArithmetic, deriveArithmetic, deriveArithmetic, deriveArithmetic, fromBigInteger, signum, toBigDecimal, toBigDecimal

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

- Constructor Detail
  - CheckedScale0fRoundingArithmetic
```
public CheckedScale0fRoundingArithmetic(RoundingMode roundingMode)
```
    Constructor for decimal arithmetic with the given rounding.
    
    Parameters:
    
    roundingMode - the rounding mode to use for all decimal arithmetic operations
  - CheckedScale0fRoundingArithmetic
```
public CheckedScale0fRoundingArithmetic(DecimalRounding rounding)
```
    Constructor for decimal arithmetic with the given rounding.
    
    Parameters:
    
    rounding - the rounding to apply to all decimal arithmetic operations
- Method Detail
  - getRoundingMode
```
public final RoundingMode getRoundingMode()
```
    Description copied from interface: DecimalArithmetic
    
    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
  - getTruncationPolicy
```
public final CheckedRounding getTruncationPolicy()
```
    Description copied from interface: DecimalArithmetic
    
    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.
    
    Specified by:
    
    getTruncationPolicy in interface DecimalArithmetic
    
    Specified by:
    
    getTruncationPolicy in class AbstractCheckedArithmetic
    
    Returns:
    
    the truncation policy defining how this DecimalArithmetic handles truncation
  - addUnscaled
```
public final long addUnscaled(long uDecimal,
                              long unscaled,
                              int scale)
```
    Description copied from interface: DecimalArithmetic
    
    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)
  - subtractUnscaled
```
public final long subtractUnscaled(long uDecimal,
                                   long unscaled,
                                   int scale)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - multiplyByUnscaled
```
public final long multiplyByUnscaled(long uDecimal,
                                     long unscaled,
                                     int scale)
```
    Description copied from interface: DecimalArithmetic
    
    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))
  - divideByUnscaled
```
public final long divideByUnscaled(long uDecimal,
                                   long unscaled,
                                   int scale)
```
    Description copied from interface: DecimalArithmetic
    
    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))
  - divide
```
public final long divide(long uDecimalDividend,
                         long uDecimalDivisor)
```
    Description copied from interface: DecimalArithmetic
    
    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)
  - multiplyByPowerOf10
```
public final long multiplyByPowerOf10(long uDecimal,
                                      int n)
```
    Description copied from interface: DecimalArithmetic
    
    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ⁿ)
  - divideByLong
```
public final long divideByLong(long uDecimalDividend,
                               long lDivisor)
```
    Description copied from interface: DecimalArithmetic
    
    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)
  - divideByPowerOf10
```
public final long divideByPowerOf10(long uDecimal,
                                    int n)
```
    Description copied from interface: DecimalArithmetic
    
    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ⁿ)
  - avg
```
public final long avg(long uDecimal1,
                      long uDecimal2)
```
    Description copied from interface: DecimalArithmetic
    
    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)
  - invert
```
public final long invert(long uDecimal)
```
    Description copied from interface: DecimalArithmetic
    
    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)
  - sqrt
```
public final long sqrt(long uDecimal)
```
    Description copied from interface: DecimalArithmetic
    
    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))
  - pow
```
public final long pow(long uDecimalBase,
                      int exponent)
```
    Description copied from interface: DecimalArithmetic
    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
  - round
```
public final long round(long uDecimal,
                        int precision)
```
    Description copied from interface: DecimalArithmetic
    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
  - shiftLeft
```
public final long shiftLeft(long uDecimal,
                            int n)
```
    Description copied from interface: DecimalArithmetic
    
    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)
    
    See Also:
    
    DecimalArithmetic.shiftRight(long, int)
  - shiftRight
```
public final long shiftRight(long uDecimal,
                             int n)
```
    Description copied from interface: DecimalArithmetic
    
    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)
    
    See Also:
    
    DecimalArithmetic.shiftLeft(long, int)
  - toFloat
```
public final float toFloat(long uDecimal)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - toDouble
```
public final double toDouble(long uDecimal)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - toUnscaled
```
public final long toUnscaled(long uDecimal,
                             int scale)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - fromFloat
```
public final long fromFloat(float value)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - fromDouble
```
public final long fromDouble(double value)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - fromUnscaled
```
public final long fromUnscaled(long unscaledValue,
                               int scale)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - fromBigDecimal
```
public final long fromBigDecimal(BigDecimal value)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - parse
```
public final long parse(String value)
```
    Description copied from interface: DecimalArithmetic
    
    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
  - parse
```
public final long parse(CharSequence value,
                        int start,
                        int end)
```
    Description copied from interface: DecimalArithmetic
    
    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

Class CheckedScale0fRoundingArithmetic

Constructor Summary

Method Summary

Methods inherited from class org.decimal4j.arithmetic.AbstractCheckedScale0fArithmetic

Methods inherited from class org.decimal4j.arithmetic.AbstractCheckedArithmetic

Methods inherited from class org.decimal4j.arithmetic.AbstractArithmetic

Methods inherited from class java.lang.Object

Constructor Detail

CheckedScale0fRoundingArithmetic

CheckedScale0fRoundingArithmetic

Method Detail

getRoundingMode

getTruncationPolicy

addUnscaled

subtractUnscaled

multiplyByUnscaled

divideByUnscaled

divide

multiplyByPowerOf10

divideByLong

divideByPowerOf10

avg

invert

sqrt

pow

round

shiftLeft

shiftRight

toFloat

toDouble

toUnscaled

fromFloat

fromDouble

fromUnscaled

fromBigDecimal

parse

parse