Class CurrencyAmount
 java.lang.Object

 com.opengamma.strata.basics.currency.CurrencyAmount

 All Implemented Interfaces:
FxConvertible<CurrencyAmount>
,java.io.Serializable
,java.lang.Comparable<CurrencyAmount>
public final class CurrencyAmount extends java.lang.Object implements FxConvertible<CurrencyAmount>, java.lang.Comparable<CurrencyAmount>, java.io.Serializable
An amount of a currency.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 aBigDecimal
is markedly slower. See theMoney
class for the alternative that usesBigDecimal
.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 thedouble
values0.1d
and0.2d
results in0.30000000000000004
rather than0.3
. As can be seen, the level of error is small, hence providing this class is used appropriately, the use ofdouble
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.
 See Also:
 Serialized Form


Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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(java.lang.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(java.util.function.DoubleUnaryOperator mapper)
Applies an operation to the amount.CurrencyAmount
minus(double amountToSubtract)
Returns a copy of thisCurrencyAmount
with the specified amount subtracted.CurrencyAmount
minus(CurrencyAmount amountToSubtract)
Returns a copy of thisCurrencyAmount
with the specified amount subtracted.CurrencyAmount
multipliedBy(double valueToMultiplyBy)
Returns a copy of thisCurrencyAmount
with the amount multiplied.CurrencyAmount
negated()
Returns a copy of thisCurrencyAmount
with the amount negated.CurrencyAmount
negative()
Returns a copy of thisCurrencyAmount
with a negative amount.static CurrencyAmount
of(Currency currency, double amount)
Obtains an instance ofCurrencyAmount
for the specified currency and amount.static CurrencyAmount
of(java.lang.String currencyCode, double amount)
Obtains an instance ofCurrencyAmount
for the specified ISO4217 three letter currency code and amount.static CurrencyAmount
parse(java.lang.String amountStr)
Parses the string to produce aCurrencyAmount
.CurrencyAmount
plus(double amountToAdd)
Returns a copy of thisCurrencyAmount
with the specified amount added.CurrencyAmount
plus(CurrencyAmount amountToAdd)
Returns a copy of thisCurrencyAmount
with the specified amount added.CurrencyAmount
positive()
Returns a copy of thisCurrencyAmount
with a positive amount.Money
toMoney()
Converts the current instance ofCurrencyAmount
to the equivalentMoney
instance.java.lang.String
toString()
Gets the amount as a string.static CurrencyAmount
zero(Currency currency)
Obtains a zero amount instance ofCurrencyAmount
for the specified currency.



Method Detail

zero
public static CurrencyAmount zero(Currency currency)
Obtains a zero amount instance ofCurrencyAmount
for the specified currency. Parameters:
currency
 the currency the amount is in Returns:
 the zero amount instance

of
public static CurrencyAmount of(Currency currency, double amount)
Obtains an instance ofCurrencyAmount
for the specified currency and amount. Parameters:
currency
 the currency the amount is inamount
 the amount of the currency to represent Returns:
 the currency amount

of
public static CurrencyAmount of(java.lang.String currencyCode, double amount)
Obtains an instance ofCurrencyAmount
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.
 Parameters:
currencyCode
 the three letter currency code, ASCII and upper caseamount
 the amount of the currency to represent Returns:
 the currency amount
 Throws:
java.lang.IllegalArgumentException
 if the currency code is invalid

parse
public static CurrencyAmount parse(java.lang.String amountStr)
Parses the string to produce aCurrencyAmount
.This parses the
toString
format of '${currency} ${amount}'. Parameters:
amountStr
 the amount string Returns:
 the currency amount
 Throws:
java.lang.IllegalArgumentException
 if the amount cannot be parsed

getCurrency
public Currency getCurrency()
Gets the currency.For example, in the value 'GBP 12.34' the currency is 'GBP'.
 Returns:
 the currency

getAmount
public double getAmount()
Gets the amount of the currency.For example, in the value 'GBP 12.34' the amount is 12.34.
 Returns:
 the amount

plus
public CurrencyAmount plus(CurrencyAmount amountToAdd)
Returns a copy of thisCurrencyAmount
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.
 Parameters:
amountToAdd
 the amount to add, in the same currency Returns:
 an amount based on this with the specified amount added
 Throws:
java.lang.IllegalArgumentException
 if the currencies are not equal

plus
public CurrencyAmount plus(double amountToAdd)
Returns a copy of thisCurrencyAmount
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.
 Parameters:
amountToAdd
 the amount to add Returns:
 an amount based on this with the specified amount added

minus
public CurrencyAmount minus(CurrencyAmount amountToSubtract)
Returns a copy of thisCurrencyAmount
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.
 Parameters:
amountToSubtract
 the amount to subtract, in the same currency Returns:
 an amount based on this with the specified amount subtracted
 Throws:
java.lang.IllegalArgumentException
 if the currencies are not equal

minus
public CurrencyAmount minus(double amountToSubtract)
Returns a copy of thisCurrencyAmount
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.
 Parameters:
amountToSubtract
 the amount to subtract Returns:
 an amount based on this with the specified amount subtracted

multipliedBy
public CurrencyAmount multipliedBy(double valueToMultiplyBy)
Returns a copy of thisCurrencyAmount
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.
 Parameters:
valueToMultiplyBy
 the scalar amount to multiply by Returns:
 an amount based on this with the amount multiplied

mapAmount
public CurrencyAmount mapAmount(java.util.function.DoubleUnaryOperator mapper)
Applies an operation to the amount.This is generally used to apply a mathematical operation to the amount. For example, the operator could multiply the amount by a constant, or take the inverse.
multiplied = base.mapAmount(value > (value < 0 ? 0 : value * 3));
 Parameters:
mapper
 the operator to be applied to the amount Returns:
 a copy of this amount with the mapping applied to the original amount

negated
public CurrencyAmount negated()
Returns a copy of thisCurrencyAmount
with the amount negated.This takes this amount and negates it. If the amount is 0.0 or 0.0 the negated amount is 0.0.
This instance is immutable and unaffected by this method.
 Returns:
 an amount based on this with the amount negated

positive
public CurrencyAmount positive()
Returns a copy of thisCurrencyAmount
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.
 Returns:
 a currency amount based on this where the amount is positive

negative
public CurrencyAmount negative()
Returns a copy of thisCurrencyAmount
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.
 Returns:
 a currency amount based on this where the amount is negative

toMoney
public Money toMoney()
Converts the current instance ofCurrencyAmount
to the equivalentMoney
instance. This will result into loss of precision in the amount, sinceMoney
is storing the amount rounded to the currency specification. Returns:
 The newly created instance of
Money
.

convertedTo
public CurrencyAmount convertedTo(Currency resultCurrency, double fxRate)
Converts this amount to an equivalent amount the specified currency.The result will be expressed in terms of the given currency, converting using the specified FX rate.
For example, if this represents 'GBP 100' and this method is called with arguments
(USD, 1.6)
then the result will be 'USD 160'. Parameters:
resultCurrency
 the currency of the resultfxRate
 the FX rate from this currency to the result currency Returns:
 the converted instance, which should be expressed in the specified currency
 Throws:
java.lang.IllegalArgumentException
 if the FX is not 1 when no conversion is required

convertedTo
public CurrencyAmount convertedTo(Currency resultCurrency, FxRateProvider rateProvider)
Converts this amount to an equivalent amount in the specified currency.The result will be expressed in terms of the given currency. If conversion is needed, the provider will be used to supply the FX rate.
 Specified by:
convertedTo
in interfaceFxConvertible<CurrencyAmount>
 Parameters:
resultCurrency
 the currency of the resultrateProvider
 the provider of FX rates Returns:
 the converted instance, in the specified currency
 Throws:
java.lang.RuntimeException
 if no FX rate could be found

compareTo
public int compareTo(CurrencyAmount other)
Compares this currency amount to another.This compares currencies alphabetically, then by amount.
 Specified by:
compareTo
in interfacejava.lang.Comparable<CurrencyAmount>
 Parameters:
other
 the other amount Returns:
 negative if less, zero if equal, positive if greater

equals
public boolean equals(java.lang.Object obj)
Checks if this currency amount equals another. Overrides:
equals
in classjava.lang.Object
 Parameters:
obj
 the other amount, null returns false Returns:
 true if equal

hashCode
public int hashCode()
Returns a suitable hash code for the currency. Overrides:
hashCode
in classjava.lang.Object
 Returns:
 the hash code

toString
public java.lang.String toString()
Gets the amount as a string.The format is the currency code, followed by a space, followed by the amount: '${currency} ${amount}'.
 Overrides:
toString
in classjava.lang.Object
 Returns:
 the currency amount

