 java.lang.Object

 org.joda.money.BigMoney

 All Implemented Interfaces:
Serializable
,Comparable<BigMoneyProvider>
,BigMoneyProvider
public final class BigMoney extends Object implements BigMoneyProvider, Comparable<BigMoneyProvider>, Serializable
An amount of money with unrestricted decimal place precision.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
BigMoney
class is not restricted to the standard decimal places and can represent an amount to any precision that aBigDecimal
can represent.This class is immutable and threadsafe.
 See Also:
 Serialized Form


Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description BigMoney
abs()
Returns a copy of this monetary value with a positive amount.int
compareTo(BigMoneyProvider other)
Compares this monetary value to another.BigMoney
convertedTo(CurrencyUnit currency, BigDecimal conversionMultipler)
Returns a copy of this monetary value converted into another currency using the specified conversion rate.BigMoney
convertRetainScale(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.BigMoney
dividedBy(double valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value using the specified rounding mode to adjust the scale.BigMoney
dividedBy(long valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value using the specified rounding mode to adjust the decimal places in the result.BigMoney
dividedBy(BigDecimal valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value using the specified rounding mode to adjust the scale.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
isCurrencyScale()
Checks if this money has the scale of the currency.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
isGreaterThanOrEqual(BigMoneyProvider other)
Checks if this monetary value is greater than or equal to another.boolean
isLessThan(BigMoneyProvider other)
Checks if this monetary value is less than another.boolean
isLessThanOrEqual(BigMoneyProvider other)
Checks if this monetary value is less or equal to 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 money)
Checks if this instance and the specified instance have the same currency.boolean
isZero()
Checks if the amount is zero.BigMoney
minus(double amountToSubtract)
Returns a copy of this monetary value with the amount subtracted.BigMoney
minus(Iterable<? extends BigMoneyProvider> moniesToSubtract)
Returns a copy of this monetary value with a collection of monetary amounts subtracted.BigMoney
minus(BigDecimal amountToSubtract)
Returns a copy of this monetary value with the amount subtracted.BigMoney
minus(BigMoneyProvider moneyToSubtract)
Returns a copy of this monetary value with the amount subtracted.BigMoney
minusMajor(long amountToSubtract)
Returns a copy of this monetary value with the amount in major units subtracted.BigMoney
minusMinor(long amountToSubtract)
Returns a copy of this monetary value with the amount in minor units subtracted.BigMoney
minusRetainScale(double amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted retaining the scale by rounding the result.BigMoney
minusRetainScale(BigDecimal amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted retaining the scale by rounding the result.BigMoney
minusRetainScale(BigMoneyProvider moneyToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount in the same currency subtracted retaining the scale by rounding the result.BigMoney
multipliedBy(double valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.BigMoney
multipliedBy(long valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.BigMoney
multipliedBy(BigDecimal valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.BigMoney
multiplyRetainScale(double valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value using the specified rounding mode to adjust the scale of the result.BigMoney
multiplyRetainScale(BigDecimal valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value using the specified rounding mode to adjust the scale of the result.BigMoney
negated()
Returns a copy of this monetary value with the amount negated.static BigMoney
of(BigMoneyProvider moneyProvider)
Obtains an instance ofBigMoney
from a provider.static BigMoney
of(CurrencyUnit currency, double amount)
Obtains an instance ofBigMoney
from adouble
using a welldefined conversion.static BigMoney
of(CurrencyUnit currency, BigDecimal amount)
Obtains an instance ofBigMoney
from aBigDecimal
.static BigMoney
ofMajor(CurrencyUnit currency, long amountMajor)
Obtains an instance ofBigMoney
from an amount in major units.static BigMoney
ofMinor(CurrencyUnit currency, long amountMinor)
Obtains an instance ofBigMoney
from an amount in minor units.static BigMoney
ofScale(CurrencyUnit currency, long unscaledAmount, int scale)
Obtains an instance ofBigMoney
from a scaled amount.static BigMoney
ofScale(CurrencyUnit currency, BigDecimal amount, int scale)
Obtains an instance ofBigMoney
from aBigDecimal
at a specific scale.static BigMoney
ofScale(CurrencyUnit currency, BigDecimal amount, int scale, RoundingMode roundingMode)
Obtains an instance ofBigMoney
from adouble
using a welldefined conversion, rounding as necessary.static BigMoney
parse(String moneyStr)
Parses an instance ofBigMoney
from a string.BigMoney
plus(double amountToAdd)
Returns a copy of this monetary value with the amount added.BigMoney
plus(Iterable<? extends BigMoneyProvider> moniesToAdd)
Returns a copy of this monetary value with a collection of monetary amounts added.BigMoney
plus(BigDecimal amountToAdd)
Returns a copy of this monetary value with the amount added.BigMoney
plus(BigMoneyProvider moneyToAdd)
Returns a copy of this monetary value with the amount added.BigMoney
plusMajor(long amountToAdd)
Returns a copy of this monetary value with the amount in major units added.BigMoney
plusMinor(long amountToAdd)
Returns a copy of this monetary value with the amount in minor units added.BigMoney
plusRetainScale(double amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added retaining the scale by rounding the result.BigMoney
plusRetainScale(BigDecimal amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added retaining the scale by rounding the result.BigMoney
plusRetainScale(BigMoneyProvider moneyToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount in the same currency added retaining the scale by rounding the result.BigMoney
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, trivially returningthis
.Money
toMoney()
Converts this money to an instance ofMoney
without rounding.Money
toMoney(RoundingMode roundingMode)
Converts this money to an instance ofMoney
.String
toString()
Gets this monetary value as a string.static BigMoney
total(Iterable<? extends BigMoneyProvider> monies)
Obtains an instance ofBigMoney
as the total value of a collection.static BigMoney
total(BigMoneyProvider... monies)
Obtains an instance ofBigMoney
as the total value of an array.static BigMoney
total(CurrencyUnit currency, Iterable<? extends BigMoneyProvider> monies)
Obtains an instance ofMoney
as the total value of a possibly empty collection.static BigMoney
total(CurrencyUnit currency, BigMoneyProvider... monies)
Obtains an instance ofMoney
as the total value of a possibly empty array.BigMoney
withAmount(double amount)
Returns a copy of this monetary value with the specified amount using a welldefined conversion from adouble
.BigMoney
withAmount(BigDecimal amount)
Returns a copy of this monetary value with the specified amount.BigMoney
withCurrencyScale()
Returns a copy of this monetary value with the scale of the currency, truncating the amount if necessary.BigMoney
withCurrencyScale(RoundingMode roundingMode)
Returns a copy of this monetary value with the scale of the currency, using the specified rounding mode if necessary.BigMoney
withCurrencyUnit(CurrencyUnit currency)
Returns a copy of this monetary value with the specified currency.BigMoney
withScale(int scale)
Returns a copy of this monetary value with the specified scale, truncating the amount if necessary.BigMoney
withScale(int scale, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified scale, using the specified rounding mode if necessary.static BigMoney
zero(CurrencyUnit currency)
Obtains an instance ofBigMoney
representing zero.static BigMoney
zero(CurrencyUnit currency, int scale)
Obtains an instance ofBigMoney
representing zero at a specific scale.



Method Detail

of
public static BigMoney of(CurrencyUnit currency, BigDecimal amount)
Obtains an instance ofBigMoney
from aBigDecimal
.This allows you to create an instance with a specific currency and amount. The scale of the money will be that of the
BigDecimal
, with a minimum scale of zero. Parameters:
currency
 the currency, not nullamount
 the amount of money, not null Returns:
 the new instance, never null
 Throws:
IllegalArgumentException
 if an invalid BigDecimal subclass has been used

of
public static BigMoney of(CurrencyUnit currency, double amount)
Obtains an instance ofBigMoney
from adouble
using a welldefined conversion.This allows you to create an instance with a specific currency and amount.
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.425d' will be converted to '1.425'. The scale of the money will be that of the BigDecimal produced, with trailing zeroes stripped, and with a minimum scale of zero. Parameters:
currency
 the currency, not nullamount
 the amount of money, not null Returns:
 the new instance, never null

ofScale
public static BigMoney ofScale(CurrencyUnit currency, BigDecimal amount, int scale)
Obtains an instance ofBigMoney
from aBigDecimal
at a specific scale.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 less than or equal to the new scale. The result will have a minimum scale of zero.
 Parameters:
currency
 the currency, not nullamount
 the amount of money, not nullscale
 the scale to use, zero or positive Returns:
 the new instance, never null
 Throws:
ArithmeticException
 if the scale exceeds the currency scale

ofScale
public static BigMoney ofScale(CurrencyUnit currency, BigDecimal amount, int scale, RoundingMode roundingMode)
Obtains an instance ofBigMoney
from adouble
using a welldefined 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 result will have a minimum scale of zero.
 Parameters:
currency
 the currency, not nullamount
 the amount of money, not nullscale
 the scale to use, zero or positiveroundingMode
 the rounding mode to use, not null Returns:
 the new instance, never null
 Throws:
ArithmeticException
 if the rounding fails

ofScale
public static BigMoney ofScale(CurrencyUnit currency, long unscaledAmount, int scale)
Obtains an instance ofBigMoney
from a scaled amount.This allows you to create an instance with a specific currency, amount and scale. The amount is defined in terms of the specified scale. The result will have a minimum scale of zero.
For example,
ofScale(USD, 234, 2)
creates the instanceUSD 2.34
. Parameters:
currency
 the currency, not nullunscaledAmount
 the unscaled amount of moneyscale
 the scale to use Returns:
 the new instance, never null

ofMajor
public static BigMoney ofMajor(CurrencyUnit currency, long amountMajor)
Obtains an instance ofBigMoney
from an amount in major units.This allows you to create an instance with a specific currency and amount. The scale of the money will be zero.
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
. 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 BigMoney ofMinor(CurrencyUnit currency, long amountMinor)
Obtains an instance ofBigMoney
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. The scale of the money will be that of the currency, such as 2 for USD or 0 for JPY.
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 BigMoney zero(CurrencyUnit currency)
Obtains an instance ofBigMoney
representing zero.The scale of the money will be zero. For example,
zero(USD)
creates the instanceUSD 0
. Parameters:
currency
 the currency, not null Returns:
 the instance representing zero, never null

zero
public static BigMoney zero(CurrencyUnit currency, int scale)
Obtains an instance ofBigMoney
representing zero at a specific scale.For example,
zero(USD, 2)
creates the instanceUSD 0.00
. Parameters:
currency
 the currency, not nullscale
 the scale to use, zero or positive Returns:
 the instance representing zero, never null
 Throws:
IllegalArgumentException
 if the scale is negative

of
public static BigMoney of(BigMoneyProvider moneyProvider)
Obtains an instance ofBigMoney
from a provider.This allows you to create an instance from any class that implements the provider, such as
Money
. This method simply callsBigMoneyProvider.toBigMoney()
checking for nulls. Parameters:
moneyProvider
 the money to convert, not null Returns:
 the new instance, never null

total
public static BigMoney total(BigMoneyProvider... monies)
Obtains an instance ofBigMoney
as the total value of an array.The array must contain at least one monetary value. Subsequent amounts are added as though using
plus(BigMoneyProvider)
. 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 BigMoney total(Iterable<? extends BigMoneyProvider> monies)
Obtains an instance ofBigMoney
as the total value of a collection.The iterable must provide at least one monetary value. Subsequent amounts are added as though using
plus(BigMoneyProvider)
. 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 BigMoney total(CurrencyUnit currency, BigMoneyProvider... monies)
Obtains an instance ofMoney
as the total value of a possibly empty array.The amounts are added as though using
plus(BigMoneyProvider)
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 BigMoney total(CurrencyUnit currency, Iterable<? extends BigMoneyProvider> monies)
Obtains an instance ofMoney
as the total value of a possibly empty collection.The amounts are added as though using
plus(BigMoneyProvider)
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 BigMoney parse(String moneyStr)
Parses an instance ofBigMoney
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
[+]?[09]*[.]?[09]*
. The spaces and numbers must be ASCII characters. This matches the output fromtoString()
.For example,
parse("USD 25")
creates the instanceUSD 25
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 BigMoney 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. No currency conversion or alteration to the scale occurs.
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

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. Negative numbers represent the opposite. For example, a scale of 2 means that the money will have two decimal places such as 'USD 43.25'. The scale of will not be negative. Returns:
 the scale in use
 See Also:
withScale(int)

isCurrencyScale
public boolean isCurrencyScale()
Checks if this money has the scale of the currency.Each currency has a default scale, such as 2 for USD and 0 for JPY. This method checks if the current scale matches the default scale.
 Returns:
 true if the scale equals the current default scale

withScale
public BigMoney withScale(int scale)
Returns a copy of this monetary value with the specified scale, truncating the amount if necessary.The returned instance will have this currency and the new scaled amount. For example, scaling 'USD 43.2' to a scale of 2 will yield 'USD 43.20'. No rounding is performed on the amount, so it must have a scale less than or equal to the new scale. A negative scale may be passed in, but the result will have a minimum scale of zero.
This instance is immutable and unaffected by this method.
 Parameters:
scale
 the scale to use Returns:
 the new instance with the input amount set, never null
 Throws:
ArithmeticException
 if the rounding fails

withScale
public BigMoney withScale(int scale, RoundingMode roundingMode)
Returns a copy of this monetary value with the specified scale, using the specified rounding mode if necessary.The returned instance will have this currency and the new scaled amount. For example, scaling 'USD 43.271' to a scale of 1 with HALF_EVEN rounding will yield 'USD 43.3'. A negative scale may be passed in, but the result will have a minimum scale of zero.
This instance is immutable and unaffected by this method.
 Parameters:
scale
 the scale to useroundingMode
 the rounding mode to use, not null Returns:
 the new instance with the input amount set, never null
 Throws:
ArithmeticException
 if the rounding fails

withCurrencyScale
public BigMoney withCurrencyScale()
Returns a copy of this monetary value with the scale of the currency, truncating the amount if necessary.The returned instance will have this currency and the new scaled amount. For example, scaling 'USD 43.271' will yield 'USD 43.27' as USD has a scale of 2. No rounding is performed on the amount, so it must have a scale less than or equal to the new scale.
This instance is immutable and unaffected by this method.
 Returns:
 the new instance with the input amount set, never null
 Throws:
ArithmeticException
 if the rounding fails

withCurrencyScale
public BigMoney withCurrencyScale(RoundingMode roundingMode)
Returns a copy of this monetary value with the scale of the currency, using the specified rounding mode if necessary.The returned instance will have this currency and the new scaled amount. For example, scaling 'USD 43.271' will yield 'USD 43.27' as USD has a scale of 2.
This instance is immutable and unaffected by this method.
 Parameters:
roundingMode
 the rounding mode to use, not null Returns:
 the new instance with the input amount set, never null
 Throws:
ArithmeticException
 if the rounding fails

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 BigMoney 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. The scale of the returned instance will be that of the specified BigDecimal.
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

withAmount
public BigMoney withAmount(double amount)
Returns a copy of this monetary value with the specified amount using a welldefined conversion from adouble
.The returned instance will have this currency and the new amount.
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.425d' will be converted to '1.425'. The scale of the money will be that of the BigDecimal produced.This instance is immutable and unaffected by this method.
 Parameters:
amount
 the monetary amount to set in the returned instance Returns:
 the new instance with the input amount set, never null

plus
public BigMoney plus(Iterable<? extends BigMoneyProvider> 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 are added as though using
plus(BigMoneyProvider)
. 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 BigMoney plus(BigMoneyProvider 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.
No precision is lost in the result. The scale of the result will be the maximum of the two scales. For example, 'USD 25.95' plus 'USD 3.021' gives 'USD 28.971'.
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 BigMoney 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 precision is lost in the result. The scale of the result will be the maximum of the two scales. For example, 'USD 25.95' plus '3.021' gives 'USD 28.971'.
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

plus
public BigMoney 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 precision is lost in the result. The scale of the result will be the maximum of the two scales. For example, 'USD 25.95' plus '3.021d' gives 'USD 28.971'.
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

plusMajor
public BigMoney plusMajor(long amountToAdd)
Returns a copy of this monetary value with the amount in major units added.This adds the specified amount in major units to this monetary amount, returning a new object. The minor units will be untouched in the result.
No precision is lost in the result. The scale of the result will be the maximum of the current scale and 0. 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 BigMoney plusMinor(long amountToAdd)
Returns a copy of this monetary value with the amount in minor units added.This adds the specified amount in minor units to this monetary amount, returning a new object.
No precision is lost in the result. The scale of the result will be the maximum of the current scale and the default currency scale. 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

plusRetainScale
public BigMoney plusRetainScale(BigMoneyProvider moneyToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount in the same currency added retaining the scale by rounding the result.The scale of the result will be the same as the scale of this instance. For example,'USD 25.95' plus 'USD 3.021' gives 'USD 28.97' with most rounding modes.
This instance is immutable and unaffected by this method.
 Parameters:
moneyToAdd
 the monetary value to add, not nullroundingMode
 the rounding mode to use to adjust the scale, not null Returns:
 the new instance with the input amount added, never null

plusRetainScale
public BigMoney plusRetainScale(BigDecimal amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added retaining the scale by rounding the result.The scale of the result will be the same as the scale of this instance. For example,'USD 25.95' plus '3.021' gives 'USD 28.97' with most rounding modes.
This instance is immutable and unaffected by this method.
 Parameters:
amountToAdd
 the monetary value to add, not nullroundingMode
 the rounding mode to use to adjust the scale, not null Returns:
 the new instance with the input amount added, never null

plusRetainScale
public BigMoney plusRetainScale(double amountToAdd, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount added retaining the scale by rounding the result.The scale of the result will be the same as the scale of this instance. For example,'USD 25.95' plus '3.021d' gives 'USD 28.97' with most rounding modes.
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 to adjust the scale, not null Returns:
 the new instance with the input amount added, never null

minus
public BigMoney minus(Iterable<? extends BigMoneyProvider> 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 are subtracted one by one as though using
minus(BigMoneyProvider)
. 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 BigMoney minus(BigMoneyProvider 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.
No precision is lost in the result. The scale of the result will be the maximum of the two scales. For example,'USD 25.95' minus 'USD 3.021' gives 'USD 22.929'.
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 BigMoney 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 precision is lost in the result. The scale of the result will be the maximum of the two scales. For example,'USD 25.95' minus '3.021' gives 'USD 22.929'.
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

minus
public BigMoney 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 precision is lost in the result. The scale of the result will be the maximum of the two scales. For example,'USD 25.95' minus '3.021d' gives 'USD 22.929'.
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

minusMajor
public BigMoney minusMajor(long amountToSubtract)
Returns a copy of this monetary value with the amount in major units subtracted.This subtracts the specified amount in major units from this monetary amount, returning a new object. The minor units will be untouched in the result.
No precision is lost in the result. The scale of the result will be the maximum of the current scale and 0. 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 BigMoney minusMinor(long amountToSubtract)
Returns a copy of this monetary value with the amount in minor units subtracted.This subtracts the specified amount in minor units from this monetary amount, returning a new object.
No precision is lost in the result. The scale of the result will be the maximum of the current scale and the default currency scale. 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

minusRetainScale
public BigMoney minusRetainScale(BigMoneyProvider moneyToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount in the same currency subtracted retaining the scale by rounding the result.The scale of the result will be the same as the scale of this instance. For example,'USD 25.95' minus 'USD 3.029' gives 'USD 22.92 with most rounding modes.
This instance is immutable and unaffected by this method.
 Parameters:
moneyToSubtract
 the monetary value to add, not nullroundingMode
 the rounding mode to use to adjust the scale, not null Returns:
 the new instance with the input amount subtracted, never null

minusRetainScale
public BigMoney minusRetainScale(BigDecimal amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted retaining the scale by rounding the result.The scale of the result will be the same as the scale of this instance. For example,'USD 25.95' minus '3.029' gives 'USD 22.92' with most rounding modes.
This instance is immutable and unaffected by this method.
 Parameters:
amountToSubtract
 the monetary value to add, not nullroundingMode
 the rounding mode to use to adjust the scale, not null Returns:
 the new instance with the input amount subtracted, never null

minusRetainScale
public BigMoney minusRetainScale(double amountToSubtract, RoundingMode roundingMode)
Returns a copy of this monetary value with the amount subtracted retaining the scale by rounding the result.The scale of the result will be the same as the scale of this instance. For example,'USD 25.95' minus '3.029d' gives 'USD 22.92' with most rounding modes.
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 add, not nullroundingMode
 the rounding mode to use to adjust the scale, not null Returns:
 the new instance with the input amount subtracted, never null

multipliedBy
public BigMoney multipliedBy(BigDecimal valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.No precision is lost in the result. The result has a scale equal to the sum of the two scales. For example, 'USD 1.13' multiplied by '2.5' gives 'USD 2.825'.
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

multipliedBy
public BigMoney multipliedBy(double valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.No precision is lost in the result. The result has a scale equal to the sum of the two scales. For example, 'USD 1.13' multiplied by '2.5' gives 'USD 2.825'.
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 null Returns:
 the new multiplied instance, never null

multipliedBy
public BigMoney multipliedBy(long valueToMultiplyBy)
Returns a copy of this monetary value multiplied by the specified value.No precision is lost in the result. The result has a scale equal to the scale of this money. For example, 'USD 1.13' multiplied by '2' gives 'USD 2.26'.
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

multiplyRetainScale
public BigMoney multiplyRetainScale(BigDecimal valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value using the specified rounding mode to adjust the scale of the result.This multiplies this money by the specified value, retaining the scale of this money. This will frequently lose precision, hence the need for a rounding mode. For example, 'USD 1.13' multiplied by '2.5' and rounding down gives 'USD 2.82'.
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

multiplyRetainScale
public BigMoney multiplyRetainScale(double valueToMultiplyBy, RoundingMode roundingMode)
Returns a copy of this monetary value multiplied by the specified value using the specified rounding mode to adjust the scale of the result.This multiplies this money by the specified value, retaining the scale of this money. This will frequently lose precision, hence the need for a rounding mode. For example, 'USD 1.13' multiplied by '2.5' and rounding down gives 'USD 2.82'.
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

dividedBy
public BigMoney dividedBy(BigDecimal valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value using the specified rounding mode to adjust the scale.The result has the same scale as this instance. For example, 'USD 1.13' divided by '2.5' and rounding down gives 'USD 0.45' (amount rounded down from 0.452).
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 BigMoney dividedBy(double valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value using the specified rounding mode to adjust the scale.The result has the same scale as this instance. For example, 'USD 1.13' divided by '2.5' and rounding down gives 'USD 0.45' (amount rounded down from 0.452).
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 BigMoney dividedBy(long valueToDivideBy, RoundingMode roundingMode)
Returns a copy of this monetary value divided by the specified value using the specified rounding mode to adjust the decimal places in the result.The result has the same scale as this instance. For example, 'USD 1.13' divided by '2' and rounding down gives 'USD 0.56' (amount rounded down from 0.565).
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 zero

negated
public BigMoney 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 BigMoney 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 BigMoney rounded(int scale, RoundingMode roundingMode)
Returns a copy of this monetary value rounded to the specified scale without changing the current scale.Scale is described in
BigDecimal
and represents the point below which the monetary value is zero. Negative scales round increasingly large numbers. UnlikewithScale(int)
, this scale of the result is unchanged. 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).
 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 BigMoney convertedTo(CurrencyUnit currency, BigDecimal conversionMultipler)
Returns a copy of this monetary value converted into another currency using the specified conversion rate.The scale of the result will be the sum of the scale of this money and the scale of the multiplier. If desired, the scale of the result can be adjusted to the scale of the new currency using
withCurrencyScale()
.This instance is immutable and unaffected by this method.
 Parameters:
currency
 the new currency, not nullconversionMultipler
 the conversion factor between the currencies, not null Returns:
 the new multiplied instance, never null
 Throws:
IllegalArgumentException
 if the currency is the same as this currency and the conversion is not one; or if the conversion multiplier is negative

convertRetainScale
public BigMoney convertRetainScale(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.The result will have the same scale as this instance even though it will be in a different currency.
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 currency and the conversion is not one; or if the conversion multiplier is negativeArithmeticException
 if the rounding fails

toBigMoney
public BigMoney toBigMoney()
Implements theBigMoneyProvider
interface, trivially returningthis
. Specified by:
toBigMoney
in interfaceBigMoneyProvider
 Returns:
 the money instance, never null

toMoney
public Money toMoney()
Converts this money to an instance ofMoney
without rounding. If the scale of this money exceeds the currency scale an exception will be thrown. Returns:
 the money instance, never null
 Throws:
ArithmeticException
 if the rounding fails

toMoney
public Money toMoney(RoundingMode roundingMode)
Converts this money to an instance ofMoney
. Parameters:
roundingMode
 the rounding mode to use, not null Returns:
 the money instance, never null
 Throws:
ArithmeticException
 if the rounding fails

isSameCurrency
public boolean isSameCurrency(BigMoneyProvider money)
Checks if this instance and the specified instance have the same currency. Parameters:
money
 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. 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 ignores the scale of the amount. Thus, '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 if this is equal to 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. The compared values must be in the same currency. Parameters:
other
 the other monetary value, not null Returns:
 true if this is greater than the specified monetary value
 Throws:
CurrencyMismatchException
 if the currencies differ

isGreaterThanOrEqual
public boolean isGreaterThanOrEqual(BigMoneyProvider other)
Checks if this monetary value is greater than or equal to another. The compared values must be in the same currency. Parameters:
other
 the other monetary value, not null Returns:
 true if this is greater than or equal to 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. The compared values must be in the same currency. Parameters:
other
 the other monetary value, not null Returns:
 true if this is less than the specified monetary value
 Throws:
CurrencyMismatchException
 if the currencies differ

isLessThanOrEqual
public boolean isLessThanOrEqual(BigMoneyProvider other)
Checks if this monetary value is less or equal to than another. The compared values must be in the same currency. Parameters:
other
 the other monetary value, not null Returns:
 true if this is less than or equal to the specified monetary value
 Throws:
CurrencyMismatchException
 if the currencies differ

equals
public boolean equals(Object other)
Checks if this monetary value equals another.Like BigDecimal, this method compares the scale of the amount. Thus, 'USD 30.00' and 'USD 30' are not equal.
The compared values must be in the same currency.
 Overrides:
equals
in classObject
 Parameters:
other
 the other object, null returns false Returns:
 true if this instance equals the other instance
 See Also:
isEqual(org.joda.money.BigMoneyProvider)

hashCode
public int hashCode()
Returns a hash code for this monetary value.

toString
public String toString()
Gets this 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()
.

