Module life.expert

Class BigAmount

  • All Implemented Interfaces:
    java.lang.Comparable<Quantity>, Quantity

    public final class BigAmount
    extends java.lang.Object
    implements Quantity, java.lang.Comparable<Quantity>
    Default immutable implementation of Quantity based on BigDecimal as numeric representation. As required by Quantity this class is final, thread-safe, immutable and serializable. This class can be configured with an arbitrary AmountContext. The default AmountContext used models by default the same settings as MathContext.DECIMAL64 .
    • Field Detail

      • DEFAULT_CONTEXT

        public static final AmountContext DEFAULT_CONTEXT
        The constant DEFAULT_CONTEXT.
      • MAX_CONTEXT

        public static final AmountContext MAX_CONTEXT
        The constant MAX_CONTEXT.
    • Method Detail

      • of

        public static BigAmount of​(java.math.BigDecimal number,
                                   Unit unit)
        Creates a new instance of BigAmount, using the default AmountContext.
        Parameters:
        number - numeric value, not null.
        unit - unit unit, not null.
        Returns:
        a BigAmount combining the numeric value and unit unit.
        Throws:
        java.lang.ArithmeticException - If the number exceeds the capabilities of the default AmountContext used.
      • of

        public static BigAmount of​(java.math.BigDecimal number,
                                   Unit unit,
                                   AmountContext amountContext)
        Creates a new instance of BigAmount, using an explicit AmountContext.
        Parameters:
        number - numeric value, not null.
        unit - unit unit, not null.
        amountContext - the AmountContext to be used, if null the default AmountContext is used.
        Returns:
        a BigAmount instance based on the monetary context with the given numeric value, unit unit.
        Throws:
        java.lang.ArithmeticException - If the number exceeds the capabilities of the AmountContext used.
      • of

        public static BigAmount of​(java.lang.Number number,
                                   Unit unit)
        Creates a new instance of BigAmount, using the default AmountContext.
        Parameters:
        number - The numeric part, not null.
        unit - The target unit, not null.
        Returns:
        A new instance of BigAmount.
        Throws:
        java.lang.ArithmeticException - If the number exceeds the capabilities of the default AmountContext used.
      • of

        public static BigAmount of​(java.lang.Number number,
                                   Unit unit,
                                   AmountContext amountContext)
        Creates a new instance of BigAmount, using an explicit AmountContext.
        Parameters:
        number - The numeric part, not null.
        unit - The target unit, not null.
        amountContext - the AmountContext to be used, if null the default AmountContext is used.
        Returns:
        A new instance of BigAmount.
        Throws:
        java.lang.ArithmeticException - If the number exceeds the capabilities of the AmountContext used.
      • of

        public static BigAmount of​(java.lang.Number number,
                                   java.lang.String unitCode)
        Static factory method for creating a new instance of BigAmount.
        Parameters:
        number - The numeric part, not null.
        unitCode - The target unit as ISO unit code.
        Returns:
        A new instance of BigAmount.
      • of

        public static BigAmount of​(java.math.BigDecimal number,
                                   java.lang.String unitCode)
        Static factory method for creating a new instance of BigAmount.
        Parameters:
        number - The numeric part, not null.
        unitCode - The target unit as ISO unit code.
        Returns:
        A new instance of BigAmount.
      • of

        public static BigAmount of​(java.lang.Number number,
                                   java.lang.String unitCode,
                                   AmountContext amountContext)
        Static factory method for creating a new instance of BigAmount.
        Parameters:
        number - The numeric part, not null.
        unitCode - The target unit as ISO unit code.
        amountContext - the AmountContext to be used, if null the default AmountContext is used.
        Returns:
        A new instance of BigAmount.
      • of

        public static BigAmount of​(java.math.BigDecimal number,
                                   java.lang.String unitCode,
                                   AmountContext amountContext)
        Static factory method for creating a new instance of BigAmount.
        Parameters:
        number - The numeric part, not null.
        unitCode - The target unit as ISO unit code.
        amountContext - the AmountContext to be used, if null the default AmountContext is used.
        Returns:
        A new instance of BigAmount.
      • zero

        public static BigAmount zero​(Unit unit)
        Obtains an instance of BigAmount representing zero.
        Parameters:
        unit - the unit, not null.
        Returns:
        an instance of BigAmount representing zero.
      • ofMinor

        public static BigAmount ofMinor​(Unit unit,
                                        long amountMinor)
        Obtains an instance of BigAmount from an amount in minor units. For example, ofMinor(USD, 1234) creates the instance USD 12.34.
        Parameters:
        unit - the unit
        amountMinor - the amount of unit in the minor division of the unit
        Returns:
        the BigAmount from minor units
        Throws:
        java.lang.NullPointerException - when the unit is null
        java.lang.IllegalArgumentException - when Unit.getDefaultFractionDigits() is lesser than zero.
        Since:
        1.0.1
        See Also:
        Unit#getDefaultFractionDigits()
      • ofMinor

        public static BigAmount ofMinor​(Unit unit,
                                        long amountMinor,
                                        int fractionDigits)
        Obtains an instance of BigAmount from an amount in minor units. For example, ofMinor(USD, 1234, 2) creates the instance USD 12.34.
        Parameters:
        unit - the unit, not null
        amountMinor - the amount of unit in the minor division of the unit
        fractionDigits - number of digits
        Returns:
        the monetary amount from minor units
        Throws:
        java.lang.NullPointerException - when the unit is null
        java.lang.IllegalArgumentException - when the fractionDigits is negative
        Since:
        1.0.1
        See Also:
        Unit#getDefaultFractionDigits(), BigAmount#ofMinor(Unit , long , int)
      • from

        public static BigAmount from​(Quantity amt)
        Converts (if necessary) the given Quantity to a BigAmount instance. The AmountContext will be adapted as necessary, if the precision of the given amount exceeds the capabilities of the default AmountContext.
        Parameters:
        amt - the amount to be converted
        Returns:
        an according BigAmount instance.
      • parse

        public static BigAmount parse​(java.lang.CharSequence text)
        Obtains an instance of BigAmount from a text string such as 'EUR 25.25'.
        Parameters:
        text - the text to parse not null
        Returns:
        BigAmount instance
        Throws:
        java.lang.NumberFormatException - if the amount is not a number
        UnknownUnitException - if the unit cannot be resolved
      • getNumberStripped

        public java.math.BigDecimal getNumberStripped()
        Method that returns BigDecimal.ZERO, if isZero(), and #stripTrailingZeros() in all other cases.
        Returns:
        the stripped number value.
      • getUnit

        public Unit getUnit()
        Returns the amount’s unit, modelled as Unit. Implementations may co-variantly change the return type to a more specific implementation of Unit if desired.
        Specified by:
        getUnit in interface Quantity
        Returns:
        the unit, never null
        See Also:
        Quantity.getUnit()
      • getNumber

        public NumberValue getNumber()
        Gets the number representation of the numeric value of this item.
        Specified by:
        getNumber in interface Quantity
        Returns:
        The Number representation matching best.
      • compareTo

        public int compareTo​(Quantity o)
        Compare to int.
        Specified by:
        compareTo in interface java.lang.Comparable<Quantity>
        Parameters:
        o - the o
        Returns:
        the int
      • abs

        public BigAmount abs()
        Description copied from interface: Quantity
        Returns a Quantity whose value is the absolute value of this Quantity, and whose scale is this.scale().
        Specified by:
        abs in interface Quantity
        Returns:
        abs(this
      • divide

        public BigAmount divide​(long divisor)
        Description copied from interface: Quantity
        Returns a Quantity whose value is
        this /
         divisor
        , and whose preferred scale is
        this.scale() -
         divisor.scale()
        ; if the exact quotient cannot be represented an ArithmeticException is thrown.
        Specified by:
        divide in interface Quantity
        Parameters:
        divisor - value by which this Quantity is to be divided.
        Returns:
        this / divisor
      • divide

        public BigAmount divide​(double divisor)
        Description copied from interface: Quantity
        Returns a Quantity whose value is
        this /
         divisor
        , and whose preferred scale is
        this.scale() -
         divisor.scale()
        ; if the exact quotient cannot be represented an ArithmeticException is thrown.
        Specified by:
        divide in interface Quantity
        Parameters:
        divisor - value by which this Quantity is to be divided.
        Returns:
        this / divisor
      • multiply

        public BigAmount multiply​(long multiplicand)
        Description copied from interface: Quantity
        Returns a Quantity whose value is (this × multiplicand), and whose scale is
        this.scale() +
         multiplicand.scale()
        .
        Specified by:
        multiply in interface Quantity
        Parameters:
        multiplicand - value to be multiplied by this Quantity.
        Returns:
        this * multiplicand
      • multiply

        public BigAmount multiply​(double multiplicand)
        Description copied from interface: Quantity
        Returns a Quantity whose value is (this × multiplicand), and whose scale is
        this.scale() +
         multiplicand.scale()
        . By default the input value's scale will be rounded to accommodate the format capabilities, and no ArithmeticException is thrown if the input number's scale exceeds the capabilities.
        Specified by:
        multiply in interface Quantity
        Parameters:
        multiplicand - value to be multiplied by this Quantity. If the multiplicand's scale exceeds the capabilities of the implementation, it may be rounded implicitly.
        Returns:
        this * multiplicand
      • remainder

        public BigAmount remainder​(long divisor)
        Description copied from interface: Quantity
        Returns a Quantity 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).
        Specified by:
        remainder in interface Quantity
        Parameters:
        divisor - value by which this Quantity is to be divided.
        Returns:
        this % divisor.
      • remainder

        public BigAmount remainder​(double divisor)
        Description copied from interface: Quantity
        Returns a Quantity 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).
        Specified by:
        remainder in interface Quantity
        Parameters:
        divisor - value by which this Quantity is to be divided.
        Returns:
        this % divisor.
      • isZero

        public boolean isZero()
        Description copied from interface: Quantity
        Checks if an Quantity is zero.
        Specified by:
        isZero in interface Quantity
        Returns:
        true if signum() == 0.
      • isPositive

        public boolean isPositive()
        Description copied from interface: Quantity
        Checks if a Quantity is positive.
        Specified by:
        isPositive in interface Quantity
        Returns:
        true if signum() > 0.
      • isPositiveOrZero

        public boolean isPositiveOrZero()
        Description copied from interface: Quantity
        Checks if a Quantity is positive or zero.
        Specified by:
        isPositiveOrZero in interface Quantity
        Returns:
        true if signum() >= 0
      • isNegative

        public boolean isNegative()
        Description copied from interface: Quantity
        Checks if a Quantity is negative.
        Specified by:
        isNegative in interface Quantity
        Returns:
        true if signum() <0
      • isNegativeOrZero

        public boolean isNegativeOrZero()
        Description copied from interface: Quantity
        Checks if a Quantity is negative or zero.
        Specified by:
        isNegativeOrZero in interface Quantity
        Returns:
        true if signum() <= 0.
      • with

        public BigAmount with​(Operator operator)
        With unit.
        Specified by:
        with in interface Quantity
        Parameters:
        operator - the operator
        Returns:
        the unit
      • add

        public BigAmount add​(Quantity amount)
        Add unit.
        Specified by:
        add in interface Quantity
        Parameters:
        amount - the amount
        Returns:
        the unit
      • divide

        public BigAmount divide​(java.lang.Number divisor)
        Description copied from interface: Quantity
        Returns a Quantity whose value is
        this /
         divisor
        , and whose preferred scale is
        this.scale() -
         divisor.scale()
        ; if the exact quotient cannot be represented an ArithmeticException is thrown.
        Specified by:
        divide in interface Quantity
        Parameters:
        divisor - value by which this Quantity is to be divided.
        Returns:
        this / divisor
      • divideToIntegralValue

        public BigAmount divideToIntegralValue​(long divisor)
        Description copied from interface: Quantity
        Returns a Quantity whose value is the integer part of the quotient
        this / divisor
        rounded down. The preferred scale of the result is
        this.scale() -
         divisor.scale()
        .
        Specified by:
        divideToIntegralValue in interface Quantity
        Parameters:
        divisor - value by which this BigDecimal is to be divided.
        Returns:
        The integer part of this / divisor.
        See Also:
        java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)
      • divideToIntegralValue

        public BigAmount divideToIntegralValue​(double divisor)
        Description copied from interface: Quantity
        Returns a Quantity whose value is the integer part of the quotient
        this / divisor
        rounded down. The preferred scale of the result is
        this.scale() - divisor.scale()
        .
        Specified by:
        divideToIntegralValue in interface Quantity
        Parameters:
        divisor - value by which this BigDecimal is to be divided.
        Returns:
        The integer part of this / divisor.
        See Also:
        java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)
      • divideToIntegralValue

        public BigAmount divideToIntegralValue​(java.lang.Number divisor)
        Description copied from interface: Quantity
        Returns a Quantity whose value is the integer part of the quotient
        this / divisor
        rounded down. The preferred scale of the result is
        this.scale() -
         divisor.scale()
        .
        Specified by:
        divideToIntegralValue in interface Quantity
        Parameters:
        divisor - value by which this BigDecimal is to be divided.
        Returns:
        The integer part of this / divisor.
        See Also:
        java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)java.math.BigDecimal#divideToIntegralValue(java.math.BigDecimal)
      • multiply

        public BigAmount multiply​(java.lang.Number multiplicand)
        Description copied from interface: Quantity
        Returns a Quantity whose value is (this × multiplicand) , and whose scale is
        this.scale() +
         multiplicand.scale()
        .
        Specified by:
        multiply in interface Quantity
        Parameters:
        multiplicand - value to be multiplied by this Quantity. If the multiplicand's scale exceeds the capabilities of the implementation, it may be rounded implicitly.
        Returns:
        this * multiplicand
      • negate

        public BigAmount negate()
        Description copied from interface: Quantity
        Returns a Quantity whose value is
        -this
        , and whose scale is this.scale().
        Specified by:
        negate in interface Quantity
        Returns:
        -this.
      • plus

        public BigAmount plus()
        Description copied from interface: Quantity
        Returns a Quantity whose value is
        +this
        , with rounding according to the context settings.
        Specified by:
        plus in interface Quantity
        Returns:
        this, rounded as necessary. A zero result will have a scale of 0.
        See Also:
        java.math.BigDecimal#plus()java.math.BigDecimal#plus()java.math.BigDecimal#plus()java.math.BigDecimal#plus()java.math.BigDecimal#plus()
      • subtract

        public BigAmount subtract​(Quantity amount)
        Subtract unit.
        Specified by:
        subtract in interface Quantity
        Parameters:
        amount - the subtrahend
        Returns:
        the unit
      • stripTrailingZeros

        public BigAmount stripTrailingZeros()
        Description copied from interface: Quantity
        Returns a Quantity which is numerically equal to this one but with any trailing zeros removed from the representation. For example, stripping the trailing zeros from the Quantity value UNIT 600.0, which has [BigInteger, scale] components equals to [6000, 1], yields 6E2 with [ BigInteger, scale] components equals to [6, -2]
        Specified by:
        stripTrailingZeros in interface Quantity
        Returns:
        a numerically equal Quantity with any trailing zeros removed.
      • remainder

        public BigAmount remainder​(java.lang.Number divisor)
        Description copied from interface: Quantity
        Returns a Quantity 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).
        Specified by:
        remainder in interface Quantity
        Parameters:
        divisor - value by which this Quantity is to be divided.
        Returns:
        this % divisor.
      • scaleByPowerOfTen

        public BigAmount scaleByPowerOfTen​(int power)
        Description copied from interface: Quantity
        Returns a Quantity whose numerical value is equal to ( this * 10n). The scale of the result is
        this.scale() - n
        .
        Specified by:
        scaleByPowerOfTen in interface Quantity
        Parameters:
        power - the power.
        Returns:
        the calculated amount value.
      • signum

        public int signum()
        Description copied from interface: Quantity
        Returns the signum function of this Quantity.
        Specified by:
        signum in interface Quantity
        Returns:
        -1, 0, or 1 as the value of this Quantity is negative, zero, or positive.
      • isLessThan

        public boolean isLessThan​(Quantity amount)
        Is less than boolean.
        Specified by:
        isLessThan in interface Quantity
        Parameters:
        amount - the amount
        Returns:
        the boolean
      • isLessThanOrEqualTo

        public boolean isLessThanOrEqualTo​(Quantity amount)
        Is less than or equal to boolean.
        Specified by:
        isLessThanOrEqualTo in interface Quantity
        Parameters:
        amount - the amount
        Returns:
        the boolean
      • isGreaterThan

        public boolean isGreaterThan​(Quantity amount)
        Is greater than boolean.
        Specified by:
        isGreaterThan in interface Quantity
        Parameters:
        amount - the amount
        Returns:
        the boolean
      • isGreaterThanOrEqualTo

        public boolean isGreaterThanOrEqualTo​(Quantity amount)
        Is greater than or equal to boolean.
        Specified by:
        isGreaterThanOrEqualTo in interface Quantity
        Parameters:
        amount - the amount
        Returns:
        the boolean
      • isEqualTo

        public boolean isEqualTo​(Quantity amount)
        Is equal to boolean.
        Specified by:
        isEqualTo in interface Quantity
        Parameters:
        amount - the amount
        Returns:
        the boolean
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object