- java.lang.Object
-
- org.joda.money.Money
-
- All Implemented Interfaces:
Serializable
,Comparable<BigMoneyProvider>
,BigMoneyProvider
public final class Money extends Object implements BigMoneyProvider, Comparable<BigMoneyProvider>, Serializable
An amount of money with the standard decimal places defined by the currency.This class represents a quantity of money, stored as a
BigDecimal
amount in a singlecurrency
.Every currency has a certain standard number of decimal places. This is typically 2 (Euro, British Pound, US Dollar) but might be 0 (Japanese Yen), 1 (Vietnamese Dong) or 3 (Bahrain Dinar). The
Money
class is fixed to this number of decimal places.For example, US dollars has a standard number of decimal places of 2. The major units are dollars. The minor units are cents, 100 to the dollar. This class does not allow calculations on fractions of a cent.
This class is immutable and thread-safe.
- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Money
abs()
Returns a copy of this monetary value with a positive amount.int
compareTo(BigMoneyProvider other)
Compares this monetary value to another.Money
convertedTo(CurrencyUnit currency, BigDecimal conversionMultipler, RoundingMode roundingMode)
Returns a copy of this monetary value converted into another currency using the specified conversion rate, with a rounding mode used to adjust the decimal places in the result.Money
dividedBy(double valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value.Money
dividedBy(long valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value.Money
dividedBy(BigDecimal valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value.boolean
equals(Object other)
Checks if this monetary value equals another.BigDecimal
getAmount()
Gets the amount.BigDecimal
getAmountMajor()
Gets the amount in major units as aBigDecimal
with scale 0.int
getAmountMajorInt()
Gets the amount in major units as anint
.long
getAmountMajorLong()
Gets the amount in major units as along
.BigDecimal
getAmountMinor()
Gets the amount in minor units as aBigDecimal
with scale 0.int
getAmountMinorInt()
Gets the amount in minor units as anint
.long
getAmountMinorLong()
Gets the amount in minor units as along
.CurrencyUnit
getCurrencyUnit()
Gets the currency.int
getMinorPart()
Gets the minor part of the amount.int
getScale()
Gets the scale of theBigDecimal
amount.int
hashCode()
Returns a hash code for this monetary value.boolean
isEqual(BigMoneyProvider other)
Checks if this monetary value is equal to another.boolean
isGreaterThan(BigMoneyProvider other)
Checks if this monetary value is greater than another.boolean
isLessThan(BigMoneyProvider other)
Checks if this monetary value is less than another.boolean
isNegative()
Checks if the amount is less than zero.boolean
isNegativeOrZero()
Checks if the amount is zero or less.boolean
isPositive()
Checks if the amount is greater than zero.boolean
isPositiveOrZero()
Checks if the amount is zero or greater.boolean
isSameCurrency(BigMoneyProvider other)
Checks if this instance and the specified instance have the same currency.boolean
isZero()
Checks if the amount is zero.Money
minus(double amountToSubtract)
Returns a copy of this monetary value with the amount subtracted.Money
minus(double amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted.Money
minus(Iterable<Money> moniesToSubtract)
Returns a copy of this monetary value with a collection of monetary amounts subtracted.Money
minus(BigDecimal amountToSubtract)
Returns a copy of this monetary value with the amount subtracted.Money
minus(BigDecimal amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted.Money
minus(Money moneyToSubtract)
Returns a copy of this monetary value with the amount subtracted.Money
minusMajor(long amountToSubtract)
Returns a copy of this monetary value with the amount in major units subtracted.Money
minusMinor(long amountToSubtract)
Returns a copy of this monetary value with the amount in minor units subtracted.Money
multipliedBy(double valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value.Money
multipliedBy(long valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.Money
multipliedBy(BigDecimal valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value.Money
negated()
Returns a copy of this monetary value with the amount negated.static Money
of(BigMoneyProvider moneyProvider)
Obtains an instance ofMoney
from a provider.static Money
of(BigMoneyProvider moneyProvider, RoundingMode roundingMode)
Obtains an instance ofMoney
from a provider, rounding as necessary.static Money
of(CurrencyUnit currency, double amount)
Obtains an instance ofMoney
from adouble
using a well-defined conversion.static Money
of(CurrencyUnit currency, double amount, RoundingMode roundingMode)
Obtains an instance ofMoney
from adouble
using a well-defined conversion, rounding as necessary.static Money
of(CurrencyUnit currency, BigDecimal amount)
Obtains an instance ofMoney
from aBigDecimal
.static Money
of(CurrencyUnit currency, BigDecimal amount, RoundingMode roundingMode)
Obtains an instance ofMoney
from aBigDecimal
, rounding as necessary.static Money
ofMajor(CurrencyUnit currency, long amountMajor)
Obtains an instance ofMoney
from an amount in major units.static Money
ofMinor(CurrencyUnit currency, long amountMinor)
Obtains an instance ofMoney
from an amount in minor units.static Money
parse(String moneyStr)
Parses an instance ofMoney
from a string.Money
plus(double amountToAdd)
Returns a copy of this monetary value with the amount added.Money
plus(double amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added.Money
plus(Iterable<Money> moniesToAdd)
Returns a copy of this monetary value with a collection of monetary amounts added.Money
plus(BigDecimal amountToAdd)
Returns a copy of this monetary value with the amount added.Money
plus(BigDecimal amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added.Money
plus(Money moneyToAdd)
Returns a copy of this monetary value with the amount added.Money
plusMajor(long amountToAdd)
Returns a copy of this monetary value with the amount in major units added.Money
plusMinor(long amountToAdd)
Returns a copy of this monetary value with the amount in minor units added.Money
rounded(int scale, RoundingMode roundingMode)
Returns a copy of this monetary value rounded to the specified scale without changing the current scale.BigMoney
toBigMoney()
Implements theBigMoneyProvider
interface, returning aBigMoney
instance with the same currency, amount and scale.String
toString()
Gets the monetary value as a string.static Money
total(Iterable<Money> monies)
Obtains an instance ofMoney
as the total value of a collection.static Money
total(CurrencyUnit currency, Iterable<Money> monies)
Obtains an instance ofMoney
as the total value of a possibly empty collection.static Money
total(CurrencyUnit currency, Money... monies)
Obtains an instance ofMoney
as the total value of a possibly empty array.static Money
total(Money... monies)
Obtains an instance ofMoney
as the total value of an array.Money
withAmount(double amount)
Returns a copy of this monetary value with the specified amount using a well-defined conversion from adouble
.Money
withAmount(double amount, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified amount using a well-defined conversion from adouble
.Money
withAmount(BigDecimal amount)
Returns a copy of this monetary value with the specified amount.Money
withAmount(BigDecimal amount, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified amount.Money
withCurrencyUnit(CurrencyUnit currency)
Returns a copy of this monetary value with the specified currency.Money
withCurrencyUnit(CurrencyUnit currency, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified currency.static Money
zero(CurrencyUnit currency)
Obtains an instance ofMoney
representing zero.
-
-
-
Method Detail
-
of
public static Money of(CurrencyUnit currency, BigDecimal amount)
Obtains an instance ofMoney
from aBigDecimal
.This allows you to create an instance with a specific currency and amount. No rounding is performed on the amount, so it must have a scale compatible with the currency.
- Parameters:
currency
- the currency, not nullamount
- the amount of money, not null- Returns:
- the new instance, never null
- Throws:
ArithmeticException
- if the scale exceeds the currency scale
-
of
public static Money of(CurrencyUnit currency, BigDecimal amount, RoundingMode roundingMode)
Obtains an instance ofMoney
from aBigDecimal
, rounding as necessary.This allows you to create an instance with a specific currency and amount. If the amount has a scale in excess of the scale of the currency then the excess fractional digits are rounded using the rounding mode.
- Parameters:
currency
- the currency, not nullamount
- the amount of money, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new instance, never null
- Throws:
ArithmeticException
- if the rounding fails
-
of
public static Money of(CurrencyUnit currency, double amount)
Obtains an instance ofMoney
from adouble
using a well-defined conversion.This allows you to create an instance with a specific currency and amount. No rounding is performed on the amount, so it must have a scale compatible with the currency.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.- Parameters:
currency
- the currency, not nullamount
- the amount of money, not null- Returns:
- the new instance, never null
- Throws:
ArithmeticException
- if the scale exceeds the currency scale
-
of
public static Money of(CurrencyUnit currency, double amount, RoundingMode roundingMode)
Obtains an instance ofMoney
from adouble
using a well-defined conversion, rounding as necessary.This allows you to create an instance with a specific currency and amount. If the amount has a scale in excess of the scale of the currency then the excess fractional digits are rounded using the rounding mode.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.- Parameters:
currency
- the currency, not nullamount
- the amount of money, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new instance, never null
- Throws:
ArithmeticException
- if the rounding fails
-
ofMajor
public static Money ofMajor(CurrencyUnit currency, long amountMajor)
Obtains an instance ofMoney
from an amount in major units.This allows you to create an instance with a specific currency and amount. The amount is a whole number only. Thus you can initialise the value 'USD 20', but not the value 'USD 20.32'. For example,
ofMajor(USD, 25)
creates the instanceUSD 25.00
.- Parameters:
currency
- the currency, not nullamountMajor
- the amount of money in the major division of the currency- Returns:
- the new instance, never null
-
ofMinor
public static Money ofMinor(CurrencyUnit currency, long amountMinor)
Obtains an instance ofMoney
from an amount in minor units.This allows you to create an instance with a specific currency and amount expressed in terms of the minor unit. For example, if constructing US Dollars, the input to this method represents cents. Note that when a currency has zero decimal places, the major and minor units are the same. For example,
ofMinor(USD, 2595)
creates the instanceUSD 25.95
.- Parameters:
currency
- the currency, not nullamountMinor
- the amount of money in the minor division of the currency- Returns:
- the new instance, never null
-
zero
public static Money zero(CurrencyUnit currency)
Obtains an instance ofMoney
representing zero.For example,
zero(USD)
creates the instanceUSD 0.00
.- Parameters:
currency
- the currency, not null- Returns:
- the instance representing zero, never null
-
of
public static Money of(BigMoneyProvider moneyProvider)
Obtains an instance ofMoney
from a provider.This allows you to create an instance from any class that implements the provider, such as
BigMoney
. No rounding is performed on the amount, so it must have a scale compatible with the currency.- Parameters:
moneyProvider
- the money to convert, not null- Returns:
- the new instance, never null
- Throws:
ArithmeticException
- if the scale exceeds the currency scale
-
of
public static Money of(BigMoneyProvider moneyProvider, RoundingMode roundingMode)
Obtains an instance ofMoney
from a provider, rounding as necessary.This allows you to create an instance from any class that implements the provider, such as
BigMoney
. The rounding mode is used to adjust the scale to the scale of the currency.- Parameters:
moneyProvider
- the money to convert, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new instance, never null
- Throws:
ArithmeticException
- if the rounding fails
-
total
public static Money total(Money... monies)
Obtains an instance ofMoney
as the total value of an array.The array must contain at least one monetary value. Subsequent amounts are added as though using
plus(Money)
. All amounts must be in the same currency.- Parameters:
monies
- the monetary values to total, not empty, no null elements, not null- Returns:
- the total, never null
- Throws:
IllegalArgumentException
- if the array is emptyCurrencyMismatchException
- if the currencies differ
-
total
public static Money total(Iterable<Money> monies)
Obtains an instance ofMoney
as the total value of a collection.The iterable must provide at least one monetary value. Subsequent amounts are added as though using
plus(Money)
. All amounts must be in the same currency.- Parameters:
monies
- the monetary values to total, not empty, no null elements, not null- Returns:
- the total, never null
- Throws:
IllegalArgumentException
- if the iterable is emptyCurrencyMismatchException
- if the currencies differ
-
total
public static Money total(CurrencyUnit currency, Money... monies)
Obtains an instance ofMoney
as the total value of a possibly empty array.The amounts are added as though using
plus(Money)
starting from zero in the specified currency. All amounts must be in the same currency.- Parameters:
currency
- the currency to total in, not nullmonies
- the monetary values to total, no null elements, not null- Returns:
- the total, never null
- Throws:
CurrencyMismatchException
- if the currencies differ
-
total
public static Money total(CurrencyUnit currency, Iterable<Money> monies)
Obtains an instance ofMoney
as the total value of a possibly empty collection.The amounts are added as though using
plus(Money)
starting from zero in the specified currency. All amounts must be in the same currency.- Parameters:
currency
- the currency to total in, not nullmonies
- the monetary values to total, no null elements, not null- Returns:
- the total, never null
- Throws:
CurrencyMismatchException
- if the currencies differ
-
parse
public static Money parse(String moneyStr)
Parses an instance ofMoney
from a string.The string format is '$currencyCode $amount' where there may be zero to many spaces between the two parts. The currency code must be a valid three letter currency. The amount must match the regular expression
[+-]?[0-9]*[.]?[0-9]*
. The spaces and numbers must be ASCII characters. This matches the output fromtoString()
.For example,
parse("USD 25")
creates the instanceUSD 25.00
whileparse("USD 25.95")
creates the instanceUSD 25.95
.- Parameters:
moneyStr
- the money string to parse, not null- Returns:
- the parsed instance, never null
- Throws:
IllegalArgumentException
- if the string is malformedArithmeticException
- if the amount is too large
-
getCurrencyUnit
public CurrencyUnit getCurrencyUnit()
Gets the currency.- Returns:
- the currency, never null
-
withCurrencyUnit
public Money withCurrencyUnit(CurrencyUnit currency)
Returns a copy of this monetary value with the specified currency.The returned instance will have the specified currency and the amount from this instance. If the scale differs between the currencies such that rounding would be required, then an exception is thrown.
This instance is immutable and unaffected by this method.
- Parameters:
currency
- the currency to use, not null- Returns:
- the new instance with the input currency set, never null
- Throws:
ArithmeticException
- if the scale of the new currency is less than the scale of this currency
-
withCurrencyUnit
public Money withCurrencyUnit(CurrencyUnit currency, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified currency.The returned instance will have the specified currency and the amount from this instance. If the number of decimal places differs between the currencies, then the amount may be rounded.
This instance is immutable and unaffected by this method.
- Parameters:
currency
- the currency to use, not nullroundingMode
- the rounding mode to use to bring the decimal places back in line, not null- Returns:
- the new instance with the input currency set, never null
- Throws:
ArithmeticException
- if the rounding fails
-
getScale
public int getScale()
Gets the scale of theBigDecimal
amount.The scale has the same meaning as in
BigDecimal
. Positive values represent the number of decimal places in use. For example, a scale of 2 means that the money will have two decimal places such as 'USD 43.25'.For
Money
, the scale is fixed and always matches that of the currency.- Returns:
- the scale in use, typically 2 but could be 0, 1 and 3
-
getAmount
public BigDecimal getAmount()
Gets the amount.This returns the value of the money as a
BigDecimal
. The scale will be the scale of this money.- Returns:
- the amount, never null
-
getAmountMajor
public BigDecimal getAmountMajor()
Gets the amount in major units as aBigDecimal
with scale 0.This returns the monetary amount in terms of the major units of the currency, truncating the amount if necessary. For example, 'EUR 2.35' will return 2, and 'BHD -1.345' will return -1.
This is returned as a
BigDecimal
rather than aBigInteger
. This is to allow further calculations to be performed on the result. Should you need aBigInteger
, simply callBigDecimal.toBigInteger()
.- Returns:
- the major units part of the amount, never null
-
getAmountMajorLong
public long getAmountMajorLong()
Gets the amount in major units as along
.This returns the monetary amount in terms of the major units of the currency, truncating the amount if necessary. For example, 'EUR 2.35' will return 2, and 'BHD -1.345' will return -1.
- Returns:
- the major units part of the amount
- Throws:
ArithmeticException
- if the amount is too large for along
-
getAmountMajorInt
public int getAmountMajorInt()
Gets the amount in major units as anint
.This returns the monetary amount in terms of the major units of the currency, truncating the amount if necessary. For example, 'EUR 2.35' will return 2, and 'BHD -1.345' will return -1.
- Returns:
- the major units part of the amount
- Throws:
ArithmeticException
- if the amount is too large for anint
-
getAmountMinor
public BigDecimal getAmountMinor()
Gets the amount in minor units as aBigDecimal
with scale 0.This returns the monetary amount in terms of the minor units of the currency, truncating the amount if necessary. For example, 'EUR 2.35' will return 235, and 'BHD -1.345' will return -1345.
This is returned as a
BigDecimal
rather than aBigInteger
. This is to allow further calculations to be performed on the result. Should you need aBigInteger
, simply callBigDecimal.toBigInteger()
.- Returns:
- the minor units part of the amount, never null
-
getAmountMinorLong
public long getAmountMinorLong()
Gets the amount in minor units as along
.This returns the monetary amount in terms of the minor units of the currency, truncating the amount if necessary. For example, 'EUR 2.35' will return 235, and 'BHD -1.345' will return -1345.
- Returns:
- the minor units part of the amount
- Throws:
ArithmeticException
- if the amount is too large for along
-
getAmountMinorInt
public int getAmountMinorInt()
Gets the amount in minor units as anint
.This returns the monetary amount in terms of the minor units of the currency, truncating the amount if necessary. For example, 'EUR 2.35' will return 235, and 'BHD -1.345' will return -1345.
- Returns:
- the minor units part of the amount
- Throws:
ArithmeticException
- if the amount is too large for anint
-
getMinorPart
public int getMinorPart()
Gets the minor part of the amount.This return the minor unit part of the monetary amount. This is defined as the amount in minor units excluding major units.
For example, EUR has a scale of 2, so the minor part is always between 0 and 99 for positive amounts, and 0 and -99 for negative amounts. Thus 'EUR 2.35' will return 35, and 'EUR -1.34' will return -34.
- Returns:
- the minor part of the amount, negative if the amount is negative
-
isZero
public boolean isZero()
Checks if the amount is zero.- Returns:
- true if the amount is zero
-
isPositive
public boolean isPositive()
Checks if the amount is greater than zero.- Returns:
- true if the amount is greater than zero
-
isPositiveOrZero
public boolean isPositiveOrZero()
Checks if the amount is zero or greater.- Returns:
- true if the amount is zero or greater
-
isNegative
public boolean isNegative()
Checks if the amount is less than zero.- Returns:
- true if the amount is less than zero
-
isNegativeOrZero
public boolean isNegativeOrZero()
Checks if the amount is zero or less.- Returns:
- true if the amount is zero or less
-
withAmount
public Money withAmount(BigDecimal amount)
Returns a copy of this monetary value with the specified amount.The returned instance will have this currency and the new amount. No rounding is performed on the amount to be added, so it must have a scale compatible with the currency.
This instance is immutable and unaffected by this method.
- Parameters:
amount
- the monetary amount to set in the returned instance, not null- Returns:
- the new instance with the input amount set, never null
- Throws:
ArithmeticException
- if the scale of the amount is too large
-
withAmount
public Money withAmount(BigDecimal amount, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified amount.The returned instance will have this currency and the new amount. If the scale of the
BigDecimal
needs to be adjusted, then it will be rounded using the specified mode.This instance is immutable and unaffected by this method.
- Parameters:
amount
- the monetary amount to set in the returned instance, not nullroundingMode
- the rounding mode to adjust the scale, not null- Returns:
- the new instance with the input amount set, never null
-
withAmount
public Money withAmount(double amount)
Returns a copy of this monetary value with the specified amount using a well-defined conversion from adouble
.The returned instance will have this currency and the new amount. No rounding is performed on the amount to be added, so it must have a scale compatible with the currency.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
amount
- the monetary amount to set in the returned instance, not null- Returns:
- the new instance with the input amount set, never null
- Throws:
ArithmeticException
- if the scale of the amount is too large
-
withAmount
public Money withAmount(double amount, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified amount using a well-defined conversion from adouble
.The returned instance will have this currency and the new amount. If the scale of the
BigDecimal
needs to be adjusted, then it will be rounded using the specified mode.The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
amount
- the monetary amount to set in the returned instance, not nullroundingMode
- the rounding mode to adjust the scale, not null- Returns:
- the new instance with the input amount set, never null
-
plus
public Money plus(Iterable<Money> moniesToAdd)
Returns a copy of this monetary value with a collection of monetary amounts added.This adds the specified amounts to this monetary amount, returning a new object. The amounts must be in the same currency.
This instance is immutable and unaffected by this method.
- Parameters:
moniesToAdd
- the monetary values to add, no null elements, not null- Returns:
- the new instance with the input amounts added, never null
- Throws:
CurrencyMismatchException
- if the currencies differ
-
plus
public Money plus(Money moneyToAdd)
Returns a copy of this monetary value with the amount added.This adds the specified amount to this monetary amount, returning a new object. The amount added must be in the same currency.
The addition has no rounding issues and is always accurate. For example,'USD 25.95' plus 'USD 3.02' will 'USD 28.97'.
This instance is immutable and unaffected by this method.
- Parameters:
moneyToAdd
- the monetary value to add, not null- Returns:
- the new instance with the input amount added, never null
- Throws:
CurrencyMismatchException
- if the currencies differ
-
plus
public Money plus(BigDecimal amountToAdd)
Returns a copy of this monetary value with the amount added.This adds the specified amount to this monetary amount, returning a new object. No rounding is performed on the amount to be added, so it must have a scale compatible with the currency.
This instance is immutable and unaffected by this method.
- Parameters:
amountToAdd
- the monetary value to add, not null- Returns:
- the new instance with the input amount added, never null
- Throws:
ArithmeticException
- if the scale of the amount is too large
-
plus
public Money plus(BigDecimal amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added.This adds the specified amount to this monetary amount, returning a new object. If the amount to add exceeds the scale of the currency, then the rounding mode will be used to adjust the result.
This instance is immutable and unaffected by this method.
- Parameters:
amountToAdd
- the monetary value to add, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new instance with the input amount added, never null
-
plus
public Money plus(double amountToAdd)
Returns a copy of this monetary value with the amount added.This adds the specified amount to this monetary amount, returning a new object. No rounding is performed on the amount to be added, so it must have a scale compatible with the currency.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
amountToAdd
- the monetary value to add, not null- Returns:
- the new instance with the input amount added, never null
- Throws:
ArithmeticException
- if the scale of the amount is too large
-
plus
public Money plus(double amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added.This adds the specified amount to this monetary amount, returning a new object. If the amount to add exceeds the scale of the currency, then the rounding mode will be used to adjust the result.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
amountToAdd
- the monetary value to add, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new instance with the input amount added, never null
-
plusMajor
public Money plusMajor(long amountToAdd)
Returns a copy of this monetary value with the amount in major units added.This adds an amount in major units, leaving the minor units untouched. For example, USD 23.45 plus 138 gives USD 161.45.
This instance is immutable and unaffected by this method.
- Parameters:
amountToAdd
- the monetary value to add, not null- Returns:
- the new instance with the input amount added, never null
-
plusMinor
public Money plusMinor(long amountToAdd)
Returns a copy of this monetary value with the amount in minor units added.This adds an amount in minor units. For example, USD 23.45 plus 138 gives USD 24.83.
This instance is immutable and unaffected by this method.
- Parameters:
amountToAdd
- the monetary value to add, not null- Returns:
- the new instance with the input amount added, never null
-
minus
public Money minus(Iterable<Money> moniesToSubtract)
Returns a copy of this monetary value with a collection of monetary amounts subtracted.This subtracts the specified amounts from this monetary amount, returning a new object. The amounts must be in the same currency.
This instance is immutable and unaffected by this method.
- Parameters:
moniesToSubtract
- the monetary values to subtract, no null elements, not null- Returns:
- the new instance with the input amounts subtracted, never null
- Throws:
CurrencyMismatchException
- if the currencies differ
-
minus
public Money minus(Money moneyToSubtract)
Returns a copy of this monetary value with the amount subtracted.This subtracts the specified amount from this monetary amount, returning a new object. The amount subtracted must be in the same currency.
The subtraction has no rounding issues and is always accurate. For example,'USD 25.95' minus 'USD 3.02' will 'USD 22.93'.
This instance is immutable and unaffected by this method.
- Parameters:
moneyToSubtract
- the monetary value to subtract, not null- Returns:
- the new instance with the input amount subtracted, never null
- Throws:
CurrencyMismatchException
- if the currencies differ
-
minus
public Money minus(BigDecimal amountToSubtract)
Returns a copy of this monetary value with the amount subtracted.This subtracts the specified amount from this monetary amount, returning a new object. No rounding is performed on the amount to be subtracted, so it must have a scale compatible with the currency.
This instance is immutable and unaffected by this method.
- Parameters:
amountToSubtract
- the monetary value to subtract, not null- Returns:
- the new instance with the input amount subtracted, never null
- Throws:
ArithmeticException
- if the scale of the amount is too large
-
minus
public Money minus(BigDecimal amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted.This subtracts the specified amount from this monetary amount, returning a new object. If the amount to subtract exceeds the scale of the currency, then the rounding mode will be used to adjust the result.
This instance is immutable and unaffected by this method.
- Parameters:
amountToSubtract
- the monetary value to subtract, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new instance with the input amount subtracted, never null
-
minus
public Money minus(double amountToSubtract)
Returns a copy of this monetary value with the amount subtracted.This subtracts the specified amount from this monetary amount, returning a new object. No rounding is performed on the amount to be subtracted, so it must have a scale compatible with the currency.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
amountToSubtract
- the monetary value to subtract, not null- Returns:
- the new instance with the input amount subtracted, never null
- Throws:
ArithmeticException
- if the scale of the amount is too large
-
minus
public Money minus(double amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted.This subtracts the specified amount from this monetary amount, returning a new object. If the amount to subtract exceeds the scale of the currency, then the rounding mode will be used to adjust the result.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
amountToSubtract
- the monetary value to subtract, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new instance with the input amount subtracted, never null
-
minusMajor
public Money minusMajor(long amountToSubtract)
Returns a copy of this monetary value with the amount in major units subtracted.This subtracts an amount in major units, leaving the minor units untouched. For example, USD 23.45 minus 138 gives USD -114.55.
This instance is immutable and unaffected by this method.
- Parameters:
amountToSubtract
- the monetary value to subtract, not null- Returns:
- the new instance with the input amount subtracted, never null
-
minusMinor
public Money minusMinor(long amountToSubtract)
Returns a copy of this monetary value with the amount in minor units subtracted.This subtracts an amount in minor units. For example, USD 23.45 minus 138 gives USD 22.07.
This instance is immutable and unaffected by this method.
- Parameters:
amountToSubtract
- the monetary value to subtract, not null- Returns:
- the new instance with the input amount subtracted, never null
-
multipliedBy
public Money multipliedBy(BigDecimal valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value.This takes this amount and multiplies it by the specified value, rounding the result is rounded as specified.
This instance is immutable and unaffected by this method.
- Parameters:
valueToMultiplyBy
- the scalar value to multiply by, not nullroundingMode
- the rounding mode to use to bring the decimal places back in line, not null- Returns:
- the new multiplied instance, never null
- Throws:
ArithmeticException
- if the rounding fails
-
multipliedBy
public Money multipliedBy(double valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value.This takes this amount and multiplies it by the specified value, rounding the result is rounded as specified.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
valueToMultiplyBy
- the scalar value to multiply by, not nullroundingMode
- the rounding mode to use to bring the decimal places back in line, not null- Returns:
- the new multiplied instance, never null
- Throws:
ArithmeticException
- if the rounding fails
-
multipliedBy
public Money multipliedBy(long valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.This takes this amount and multiplies it by the specified value.
This instance is immutable and unaffected by this method.
- Parameters:
valueToMultiplyBy
- the scalar value to multiply by, not null- Returns:
- the new multiplied instance, never null
-
dividedBy
public Money dividedBy(BigDecimal valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value.This takes this amount and divides it by the specified value, rounding the result is rounded as specified.
This instance is immutable and unaffected by this method.
- Parameters:
valueToDivideBy
- the scalar value to divide by, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new divided instance, never null
- Throws:
ArithmeticException
- if dividing by zeroArithmeticException
- if the rounding fails
-
dividedBy
public Money dividedBy(double valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value.This takes this amount and divides it by the specified value, rounding the result is rounded as specified.
The amount is converted via
BigDecimal.valueOf(double)
which yields the most expected answer for most programming scenarios. Anydouble
literal in code will be converted to exactly the same BigDecimal with the same scale. For example, the literal '1.45d' will be converted to '1.45'.This instance is immutable and unaffected by this method.
- Parameters:
valueToDivideBy
- the scalar value to divide by, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new divided instance, never null
- Throws:
ArithmeticException
- if dividing by zeroArithmeticException
- if the rounding fails
-
dividedBy
public Money dividedBy(long valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value.This takes this amount and divides it by the specified value, rounding the result is rounded as specified.
This instance is immutable and unaffected by this method.
- Parameters:
valueToDivideBy
- the scalar value to divide by, not nullroundingMode
- the rounding mode to use, not null- Returns:
- the new divided instance, never null
- Throws:
ArithmeticException
- if dividing by zeroArithmeticException
- if the rounding fails
-
negated
public Money negated()
Returns a copy of this monetary value with the amount negated.This instance is immutable and unaffected by this method.
- Returns:
- the new instance with the amount negated, never null
-
abs
public Money abs()
Returns a copy of this monetary value with a positive amount.This instance is immutable and unaffected by this method.
- Returns:
- the new instance with the amount converted to be positive, never null
-
rounded
public Money rounded(int scale, RoundingMode roundingMode)
Returns a copy of this monetary value rounded to the specified scale without changing the current scale.Scale has the same meaning as in
BigDecimal
. A scale of 2 means round to 2 decimal places.- Rounding 'EUR 45.23' to a scale of -1 returns 40.00 or 50.00 depending on the rounding mode.
- Rounding 'EUR 45.23' to a scale of 0 returns 45.00 or 46.00 depending on the rounding mode.
- Rounding 'EUR 45.23' to a scale of 1 returns 45.20 or 45.30 depending on the rounding mode.
- Rounding 'EUR 45.23' to a scale of 2 has no effect (it already has that scale).
- Rounding 'EUR 45.23' to a scale of 3 has no effect (the scale is not increased).
This instance is immutable and unaffected by this method.
- Parameters:
scale
- the new scaleroundingMode
- the rounding mode to use, not null- Returns:
- the new instance with the amount converted to be positive, never null
- Throws:
ArithmeticException
- if the rounding fails
-
convertedTo
public Money convertedTo(CurrencyUnit currency, BigDecimal conversionMultipler, RoundingMode roundingMode)
Returns a copy of this monetary value converted into another currency using the specified conversion rate, with a rounding mode used to adjust the decimal places in the result.This instance is immutable and unaffected by this method.
- Parameters:
currency
- the new currency, not nullconversionMultipler
- the conversion factor between the currencies, not nullroundingMode
- the rounding mode to use to bring the decimal places back in line, not null- Returns:
- the new multiplied instance, never null
- Throws:
IllegalArgumentException
- if the currency is the same as this currencyIllegalArgumentException
- if the conversion multiplier is negativeArithmeticException
- if the rounding fails
-
toBigMoney
public BigMoney toBigMoney()
Implements theBigMoneyProvider
interface, returning aBigMoney
instance with the same currency, amount and scale.- Specified by:
toBigMoney
in interfaceBigMoneyProvider
- Returns:
- the money instance, never null
-
isSameCurrency
public boolean isSameCurrency(BigMoneyProvider other)
Checks if this instance and the specified instance have the same currency.- Parameters:
other
- the money to check, not null- Returns:
- true if they have the same currency
-
compareTo
public int compareTo(BigMoneyProvider other)
Compares this monetary value to another.This allows
Money
to be compared to anyBigMoneyProvider
. Scale is ignored in the comparison. The compared values must be in the same currency.- Specified by:
compareTo
in interfaceComparable<BigMoneyProvider>
- Parameters:
other
- the other monetary value, not null- Returns:
- -1 if this is less than , 0 if equal, 1 if greater than
- Throws:
CurrencyMismatchException
- if the currencies differ
-
isEqual
public boolean isEqual(BigMoneyProvider other)
Checks if this monetary value is equal to another.This allows
Money
to be compared to anyBigMoneyProvider
. Scale is ignored, so 'USD 30.00' and 'USD 30' are equal. The compared values must be in the same currency.- Parameters:
other
- the other monetary value, not null- Returns:
- true is this is greater than the specified monetary value
- Throws:
CurrencyMismatchException
- if the currencies differ- See Also:
equals(Object)
-
isGreaterThan
public boolean isGreaterThan(BigMoneyProvider other)
Checks if this monetary value is greater than another.This allows
Money
to be compared to anyBigMoneyProvider
. Scale is ignored in the comparison. The compared values must be in the same currency.- Parameters:
other
- the other monetary value, not null- Returns:
- true is this is greater than the specified monetary value
- Throws:
CurrencyMismatchException
- if the currencies differ
-
isLessThan
public boolean isLessThan(BigMoneyProvider other)
Checks if this monetary value is less than another.This allows
Money
to be compared to anyBigMoneyProvider
. Scale is ignored in the comparison. The compared values must be in the same currency.- Parameters:
other
- the other monetary value, not null- Returns:
- true is this is less than the specified monetary value
- Throws:
CurrencyMismatchException
- if the currencies differ
-
equals
public boolean equals(Object other)
Checks if this monetary value equals another.The comparison takes into account the scale. The compared values must be in the same currency.
-
hashCode
public int hashCode()
Returns a hash code for this monetary value.
-
toString
public String toString()
Gets the monetary value as a string.The format is the 3 letter ISO currency code, followed by a space, followed by the amount as per
BigDecimal.toPlainString()
.
-
-