## 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 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 thread-safe.

Serialized Form
• ### Method Summary

All 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 this CurrencyAmount with the specified amount subtracted.
CurrencyAmount minus​(CurrencyAmount 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​(java.lang.String currencyCode, double amount)
Obtains an instance of CurrencyAmount for the specified ISO-4217 three letter currency code and amount.
static CurrencyAmount parse​(java.lang.String amountStr)
Parses the string to produce a CurrencyAmount.
CurrencyAmount plus​(double amountToAdd)
Returns a copy of this CurrencyAmount with the specified amount added.
CurrencyAmount plus​(CurrencyAmount 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.
java.lang.String toString()
Gets the amount as a string.
static CurrencyAmount zero​(Currency currency)
Obtains a zero amount instance of CurrencyAmount for the specified currency.
• ### Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
• ### Method Detail

• #### zero

public static CurrencyAmount zero​(Currency currency)
Obtains a zero amount instance of CurrencyAmount 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 of CurrencyAmount for the specified currency and amount.
Parameters:
currency - the currency the amount is in
amount - the amount of the currency to represent
Returns:
the currency amount
• #### of

public static CurrencyAmount of​(java.lang.String currencyCode,
double amount)
Obtains an instance of CurrencyAmount for the specified ISO-4217 three letter currency code and amount.

A currency is uniquely identified by ISO-4217 three letter code. This method creates the currency if it is not known.

Parameters:
currencyCode - the three letter currency code, ASCII and upper case
amount - 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 a CurrencyAmount.

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 this 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.

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 this 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.

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 this 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.

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 this 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.

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 this 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.

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 this 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.

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

public CurrencyAmount positive()
Returns a copy of this 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.

Returns:
a currency amount based on this where the amount is positive
• #### negative

public CurrencyAmount negative()
Returns a copy of this 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.

Returns:
a currency amount based on this where the amount is negative
• #### 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 result
fxRate - the FX rate from this currency to the result currency
Returns:
the converted instance, which should be expressed in the specified currency
Throws:
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 interface FxConvertible<CurrencyAmount>
Parameters:
resultCurrency - the currency of the result
rateProvider - 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 interface java.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 class java.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 class java.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 class java.lang.Object
Returns:
the currency amount