public final class CurrencyAmount extends Object implements FxConvertible<CurrencyAmount>, Comparable<CurrencyAmount>, Serializable
This class represents a double
amount associated with a currency.
It is specifically named "CurrencyAmount" and not "Money" to indicate that
it simply holds a currency and an amount. By contrast, naming it "Money"
would imply it was a suitable choice for accounting purposes, which it is not.
This design approach has been chosen primarily for performance reasons.
Using a BigDecimal
is markedly slower.
See the Money
class for the alternative that uses BigDecimal
.
A double
is a 64 bit floating point value suitable for most calculations.
Floating point maths is
inexact
due to the conflict between binary and decimal arithmetic.
As such, there is the potential for data loss at the margins.
For example, adding the double
values 0.1d
and 0.2d
results in 0.30000000000000004
rather than 0.3
.
As can be seen, the level of error is small, hence providing this class is
used appropriately, the use of double
is acceptable.
For example, using this class to provide a meaningful result type after
calculations have completed would be an appropriate use.
This class is immutable and threadsafe.
Modifier and Type  Method and Description 

int 
compareTo(CurrencyAmount other)
Compares this currency amount to another.

CurrencyAmount 
convertedTo(Currency resultCurrency,
double fxRate)
Converts this amount to an equivalent amount the specified currency.

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

boolean 
equals(Object obj)
Checks if this currency amount equals another.

double 
getAmount()
Gets the amount of the currency.

Currency 
getCurrency()
Gets the currency.

int 
hashCode()
Returns a suitable hash code for the currency.

CurrencyAmount 
mapAmount(DoubleUnaryOperator mapper)
Applies an operation to the amount.

CurrencyAmount 
minus(CurrencyAmount amountToSubtract)
Returns a copy of this
CurrencyAmount with the specified amount subtracted. 
CurrencyAmount 
minus(double amountToSubtract)
Returns a copy of this
CurrencyAmount with the specified amount subtracted. 
CurrencyAmount 
multipliedBy(double valueToMultiplyBy)
Returns a copy of this
CurrencyAmount with the amount multiplied. 
CurrencyAmount 
negated()
Returns a copy of this
CurrencyAmount with the amount negated. 
CurrencyAmount 
negative()
Returns a copy of this
CurrencyAmount with a negative amount. 
static CurrencyAmount 
of(Currency currency,
double amount)
Obtains an instance of
CurrencyAmount for the specified currency and amount. 
static CurrencyAmount 
of(String currencyCode,
double amount)
Obtains an instance of
CurrencyAmount for the specified ISO4217
three letter currency code and amount. 
static CurrencyAmount 
parse(String amountStr)
Parses the string to produce a
CurrencyAmount . 
CurrencyAmount 
plus(CurrencyAmount amountToAdd)
Returns a copy of this
CurrencyAmount with the specified amount added. 
CurrencyAmount 
plus(double amountToAdd)
Returns a copy of this
CurrencyAmount with the specified amount added. 
CurrencyAmount 
positive()
Returns a copy of this
CurrencyAmount with a positive amount. 
Money 
toMoney()
Converts the current instance of
CurrencyAmount to the equivalent Money instance. 
String 
toString()
Gets the amount as a string.

static CurrencyAmount 
zero(Currency currency)
Obtains a zero amount instance of
CurrencyAmount for the specified currency. 
public static CurrencyAmount zero(Currency currency)
CurrencyAmount
for the specified currency.currency
 the currency the amount is inpublic static CurrencyAmount of(Currency currency, double amount)
CurrencyAmount
for the specified currency and amount.currency
 the currency the amount is inamount
 the amount of the currency to representpublic static CurrencyAmount of(String currencyCode, double amount)
CurrencyAmount
for the specified ISO4217
three letter currency code and amount.
A currency is uniquely identified by ISO4217 three letter code. This method creates the currency if it is not known.
currencyCode
 the three letter currency code, ASCII and upper caseamount
 the amount of the currency to representIllegalArgumentException
 if the currency code is invalidpublic static CurrencyAmount parse(String amountStr)
CurrencyAmount
.
This parses the toString
format of '${currency} ${amount}'.
amountStr
 the amount stringIllegalArgumentException
 if the amount cannot be parsedpublic Currency getCurrency()
For example, in the value 'GBP 12.34' the currency is 'GBP'.
public double getAmount()
For example, in the value 'GBP 12.34' the amount is 12.34.
public CurrencyAmount plus(CurrencyAmount amountToAdd)
CurrencyAmount
with the specified amount added.
This adds the specified amount to this monetary amount, returning a new object.
The addition simply uses standard double
arithmetic.
This instance is immutable and unaffected by this method.
amountToAdd
 the amount to add, in the same currencyIllegalArgumentException
 if the currencies are not equalpublic CurrencyAmount plus(double amountToAdd)
CurrencyAmount
with the specified amount added.
This adds the specified amount to this monetary amount, returning a new object.
The addition simply uses standard double
arithmetic.
This instance is immutable and unaffected by this method.
amountToAdd
 the amount to addpublic CurrencyAmount minus(CurrencyAmount amountToSubtract)
CurrencyAmount
with the specified amount subtracted.
This subtracts the specified amount to this monetary amount, returning a new object.
The addition simply uses standard double
arithmetic.
This instance is immutable and unaffected by this method.
amountToSubtract
 the amount to subtract, in the same currencyIllegalArgumentException
 if the currencies are not equalpublic CurrencyAmount minus(double amountToSubtract)
CurrencyAmount
with the specified amount subtracted.
This subtracts the specified amount to this monetary amount, returning a new object.
The addition simply uses standard double
arithmetic.
This instance is immutable and unaffected by this method.
amountToSubtract
 the amount to subtractpublic CurrencyAmount multipliedBy(double valueToMultiplyBy)
CurrencyAmount
with the amount multiplied.
This takes this amount and multiplies it by the specified value.
The multiplication simply uses standard double
arithmetic.
This instance is immutable and unaffected by this method.
valueToMultiplyBy
 the scalar amount to multiply bypublic CurrencyAmount mapAmount(DoubleUnaryOperator mapper)
This is generally used to apply a mathematical operation to the amount. For example, the operator could multiply the amount by a constant, or take the inverse.
multiplied = base.mapAmount(value > (value < 0 ? 0 : value * 3));
mapper
 the operator to be applied to the amountpublic CurrencyAmount negated()
CurrencyAmount
with the amount negated.
This takes this amount and negates it. If the amount is 0.0 or 0.0 the negated amount is 0.0.
This instance is immutable and unaffected by this method.
public CurrencyAmount positive()
CurrencyAmount
with a positive amount.
The result of this method will always be positive, where the amount is equal to Math.abs(amount)
.
This instance is immutable and unaffected by this method.
public CurrencyAmount negative()
CurrencyAmount
with a negative amount.
The result of this method will always be negative, equal to Math.abs(amount)
.
This instance is immutable and unaffected by this method.
public Money toMoney()
CurrencyAmount
to the equivalent Money
instance.
This will result into loss of precision in the amount, since Money
is storing the amount
rounded to the currency specification.Money
.public CurrencyAmount convertedTo(Currency resultCurrency, double fxRate)
The result will be expressed in terms of the given currency, converting using the specified FX rate.
For example, if this represents 'GBP 100' and this method is called with
arguments (USD, 1.6)
then the result will be 'USD 160'.
resultCurrency
 the currency of the resultfxRate
 the FX rate from this currency to the result currencyIllegalArgumentException
 if the FX is not 1 when no conversion is requiredpublic CurrencyAmount convertedTo(Currency resultCurrency, FxRateProvider rateProvider)
The result will be expressed in terms of the given currency. If conversion is needed, the provider will be used to supply the FX rate.
convertedTo
in interface FxConvertible<CurrencyAmount>
resultCurrency
 the currency of the resultrateProvider
 the provider of FX ratesRuntimeException
 if no FX rate could be foundpublic int compareTo(CurrencyAmount other)
This compares currencies alphabetically, then by amount.
compareTo
in interface Comparable<CurrencyAmount>
other
 the other amountpublic boolean equals(Object obj)
public int hashCode()
Copyright 2009Present by OpenGamma Inc. and individual contributors
Apache v2 licensed
Additional documentation can be found at strata.opengamma.io.