Class Money

    • Method Detail

      • zero

        public static Money zero​(Currency currency)
        Obtains a zero amount instance of Money for the specified currency.
        Parameters:
        currency - the currency the amount is in
        Returns:
        the zero amount instance
      • of

        public static Money of​(CurrencyAmount currencyAmount)
        Obtains an instance of Money for the specified CurrencyAmount.
        Parameters:
        currencyAmount - the instance of CurrencyAmount wrapping the currency and amount.
        Returns:
        the currency amount
      • of

        public static Money of​(BigMoney money)
        Obtains an instance of Money for the specified BigMoney.
        Parameters:
        money - the instance of BigMoney wrapping the currency and amount.
        Returns:
        the currency amount
      • of

        public static Money of​(Currency currency,
                               double amount)
        Obtains an instance of Money for the specified currency and amount.
        Parameters:
        currency - the currency the amount is in
        amount - the amount of the currency to represent
        Returns:
        the currency amount
      • of

        public static Money of​(Currency currency,
                               BigDecimal amount)
        Obtains an instance of Money for the specified currency and amount.
        Parameters:
        currency - the currency the amount is in
        amount - the amount of the currency to represent, as an instance of BigDecimal
        Returns:
        the currency amount
      • of

        public static Money of​(Currency currency,
                               Decimal amount)
        Obtains an instance of Money for the specified currency and amount.
        Parameters:
        currency - the currency the amount is in
        amount - the amount of the currency to represent, as an instance of Decimal
        Returns:
        the currency amount
      • parse

        public static Money parse​(String amountStr)
        Parses the string to produce a Money.

        This parses the toString format of '${currency} ${amount}'.

        Parameters:
        amountStr - the amount string
        Returns:
        the currency amount
        Throws:
        IllegalArgumentException - if the amount cannot be parsed
      • getCurrency

        public Currency getCurrency()
        Gets the currency.

        For example, in the value 'GBP 12.34' the currency is 'GBP'.

        Returns:
        the currency
      • getAmount

        @Deprecated
        public BigDecimal getAmount()
        Deprecated.
        Gets the numeric amount of the money, as a BigDecimal.

        For example, in the amount 'GBP 12.34' the decimal value returned is 12.34, and for 'GBP 13.40' the amount returned is '13.40'.

        Returns:
        the amount, with a scale equal to the currency minor digits
      • getValue

        public FixedScaleDecimal getValue()
        Gets the numeric amount of the money.

        For example, in the amount 'GBP 12.34' the decimal value returned is '12.34', whereas for 'GBP 13.40' the amount returned is '13.40'.

        Returns:
        the amount, with a scale equal to the currency minor digits
      • plus

        public Money plus​(Money amountToAdd)
        Returns a copy of this Money with the specified amount added.

        This adds the specified amount to this monetary amount, returning a new object.

        This instance is immutable and unaffected by this method.

        Parameters:
        amountToAdd - the amount to add, in the same currency
        Returns:
        an amount based on this with the specified amount added
        Throws:
        IllegalArgumentException - if the currencies are not equal
      • minus

        public Money minus​(Money amountToSubtract)
        Returns a copy of this Money with the specified amount subtracted.

        This subtracts the specified amount to this monetary amount, returning a new object.

        This instance is immutable and unaffected by this method.

        Parameters:
        amountToSubtract - the amount to subtract, in the same currency
        Returns:
        an amount based on this with the specified amount subtracted
        Throws:
        IllegalArgumentException - if the currencies are not equal
      • multipliedBy

        public Money multipliedBy​(long valueToMultiplyBy)
        Returns a copy of this Money with the amount multiplied.

        This takes this amount and multiplies it by the specified value.

        This instance is immutable and unaffected by this method.

        Parameters:
        valueToMultiplyBy - the scalar amount to multiply by
        Returns:
        an amount based on this with the amount multiplied
      • map

        public Money map​(UnaryOperator<Decimal> mapper)
        Applies an operation to the amount.

        This is generally used to apply a mathematical operation to the amount. For example, the operator could multiply the amount by a constant, or take the inverse.

           abs = base.mapAmount(value -> value.abs());
         
        Parameters:
        mapper - the operator to be applied to the amount
        Returns:
        a copy of this amount with the mapping applied to the original amount
      • mapAmount

        @Deprecated
        public Money mapAmount​(UnaryOperator<BigDecimal> mapper)
        Deprecated.
        Use map(UnaryOperator), potentially using a lambda decimal -> decimal.mapAsBigDecimal(mapper)
        Applies an operation to the amount.

        This is generally used to apply a mathematical operation to the amount. For example, the operator could multiply the amount by a constant, or take the inverse.

           abs = base.mapAmount(value -> value.abs());
         
        Parameters:
        mapper - the operator to be applied to the amount
        Returns:
        a copy of this amount with the mapping applied to the original amount
      • isZero

        public boolean isZero()
        Checks if the amount is zero.
        Returns:
        true if zero
      • isPositive

        public boolean isPositive()
        Checks if the amount is positive.

        Zero and negative amounts return false.

        Returns:
        true if positive
      • isNegative

        public boolean isNegative()
        Checks if the amount is negative.

        Zero and positive amounts return false.

        Returns:
        true if negative
      • negated

        public Money negated()
        Returns a copy of this Money with the amount negated.

        This takes this amount and negates it. If the amount is 0.0 or -0.0 the negated amount is 0.0.

        This instance is immutable and unaffected by this method.

        Returns:
        an amount based on this with the amount negated
      • positive

        public Money positive()
        Returns a copy of this Money with a positive amount.

        The result of this method will always be positive, where the amount is equal to abs(amount).

        This instance is immutable and unaffected by this method.

        Returns:
        an amount based on this where the amount is positive
      • negative

        public Money negative()
        Returns a copy of this Money with a negative amount.

        The result of this method will always be negative, equal to -.abs(amount).

        This instance is immutable and unaffected by this method.

        Returns:
        an amount based on this where the amount is negative
      • toCurrencyAmount

        public CurrencyAmount toCurrencyAmount()
        Converts this monetary amount to the equivalent CurrencyAmount.
        Returns:
        the equivalent CurrencyAmount
      • toBigMoney

        public BigMoney toBigMoney()
        Converts this monetary amount to the equivalent BigMoney.
        Returns:
        the equivalent BigMoney
      • convertedTo

        public Money convertedTo​(Currency resultCurrency,
                                 BigDecimal fxRate)
        Converts this amount to an equivalent amount the specified currency.

        The result will be expressed in terms of the given currency, converting using the specified FX rate.

        For example, if this represents 'GBP 100' and this method is called with arguments (USD, 1.6) then the result will be 'USD 160'.

        Parameters:
        resultCurrency - the currency of the result
        fxRate - the FX rate from this currency to the result currency
        Returns:
        the converted instance, which should be expressed in the specified currency
        Throws:
        IllegalArgumentException - if the FX is not 1 when no conversion is required
      • convertedTo

        public Money convertedTo​(Currency resultCurrency,
                                 Decimal fxRate)
        Converts this amount to an equivalent amount the specified currency.

        The result will be expressed in terms of the given currency, converting using the specified FX rate.

        For example, if this represents 'GBP 100' and this method is called with arguments (USD, 1.6) then the result will be 'USD 160'.

        Parameters:
        resultCurrency - the currency of the result
        fxRate - the FX rate from this currency to the result currency
        Returns:
        the converted instance, which should be expressed in the specified currency
        Throws:
        IllegalArgumentException - if the FX is not 1 when no conversion is required
      • convertedTo

        public Money convertedTo​(Currency resultCurrency,
                                 FxRateProvider rateProvider)
        Converts this amount to an equivalent amount in the specified currency.

        The result will be expressed in terms of the given currency. If conversion is needed, the provider will be used to supply the FX rate.

        Specified by:
        convertedTo in interface FxConvertible<Money>
        Parameters:
        resultCurrency - the currency of the result
        rateProvider - the provider of FX rates
        Returns:
        the converted instance, in the specified currency
        Throws:
        RuntimeException - if no FX rate could be found
      • compareTo

        public int compareTo​(Money other)
        Compares this money to another.

        This compares currencies alphabetically, then by amount.

        Specified by:
        compareTo in interface Comparable<Money>
        Parameters:
        other - the other amount
        Returns:
        negative if less, zero if equal, positive if greater
      • equals

        public boolean equals​(Object obj)
        Checks if this money equals another.
        Overrides:
        equals in class Object
        Parameters:
        obj - the other amount, null returns false
        Returns:
        true if equal
      • hashCode

        public int hashCode()
        Returns a suitable hash code for the currency.
        Overrides:
        hashCode in class Object
        Returns:
        the hash code
      • toString

        public String toString()
        Gets the amount as a string.

        The format is the currency code, followed by a space, followed by the amount: '${currency} ${amount}'.

        Overrides:
        toString in class Object
        Returns:
        the currency amount