Class FxRate

  • All Implemented Interfaces:
    FxRateProvider, Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean

    public final class FxRate
    extends Object
    implements FxRateProvider, org.joda.beans.ImmutableBean, Serializable
    A single foreign exchange rate between two currencies, such as 'EUR/USD 1.25'.

    This represents a rate of foreign exchange. The rate 'EUR/USD 1.25' consists of three elements - the base currency 'EUR', the counter currency 'USD' and the rate '1.25'. When performing a conversion a rate of '1.25' means that '1 EUR = 1.25 USD'.

    See CurrencyPair for the representation that does not contain a rate.

    This class is immutable and thread-safe.

    See Also:
    Serialized Form
    • Method Detail

      • of

        public static FxRate of​(Currency base,
                                Currency counter,
                                double rate)
        Obtains an instance from two currencies.

        The first currency is the base and the second is the counter. The two currencies may be the same, but if they are then the rate must be one.

        Parameters:
        base - the base currency
        counter - the counter currency
        rate - the conversion rate, greater than zero
        Returns:
        the FX rate
        Throws:
        IllegalArgumentException - if the rate is invalid
      • of

        public static FxRate of​(CurrencyPair pair,
                                double rate)
        Obtains an instance from a currency pair.

        The two currencies may be the same, but if they are then the rate must be one.

        Parameters:
        pair - the currency pair
        rate - the conversion rate, greater than zero
        Returns:
        the FX rate
        Throws:
        IllegalArgumentException - if the rate is invalid
      • parse

        public static FxRate parse​(String rateStr)
        Parses a rate from a string with format AAA/BBB RATE.

        The parsed format is '${baseCurrency}/${counterCurrency} ${rate}'. Currency parsing is case insensitive.

        Parameters:
        rateStr - the rate as a string AAA/BBB RATE
        Returns:
        the FX rate
        Throws:
        IllegalArgumentException - if the FX rate cannot be parsed
      • inverse

        public FxRate inverse()
        Gets the inverse rate.

        The inverse rate has the same currencies but in reverse order. The rate is the reciprocal of the original.

        Returns:
        the inverse pair
      • fxRate

        public double fxRate​(Currency baseCurrency,
                             Currency counterCurrency)
        Gets the FX rate for the specified currency pair.

        The rate returned is the rate from the base currency to the counter currency as defined by this formula: (1 * baseCurrency = fxRate * counterCurrency).

        This will return the rate or inverse rate, or 1 if the two input currencies are the same.

        Specified by:
        fxRate in interface FxRateProvider
        Parameters:
        baseCurrency - the base currency, to convert from
        counterCurrency - the counter currency, to convert to
        Returns:
        the FX rate for the currency pair
        Throws:
        IllegalArgumentException - if no FX rate could be found
      • crossRate

        public FxRate crossRate​(FxRate other)
        Derives an FX rate from two related FX rates.

        Given two FX rates it is possible to derive another rate if they have a currency in common. For example, given rates for EUR/GBP and EUR/CHF it is possible to derive rates for GBP/CHF. The result will always have a currency pair in the conventional order.

        The cross is only returned if the two pairs contains three currencies in total. If the inputs are invalid, an exception is thrown.

        • AAA/BBB and BBB/CCC - valid, producing AAA/CCC
        • AAA/BBB and CCC/BBB - valid, producing AAA/CCC
        • AAA/BBB and BBB/AAA - invalid, exception thrown
        • AAA/BBB and BBB/BBB - invalid, exception thrown
        • AAA/BBB and CCC/DDD - invalid, exception thrown
        Parameters:
        other - the other rates
        Returns:
        a set of FX rates derived from these rates and the other rates
        Throws:
        IllegalArgumentException - if the cross rate cannot be calculated
      • toConventional

        public FxRate toConventional()
        Returns an FX rate object representing the market convention rate between the two currencies.

        If the currency pair is the market convention pair, this method returns this, otherwise it returns an FxRate with the inverse currency pair and reciprocal rate.

        Returns:
        an FX rate object representing the market convention rate between the two currencies
      • toString

        public String toString()
        Returns the formatted string version of the currency pair.

        The format is '${baseCurrency}/${counterCurrency} ${rate}'.

        Overrides:
        toString in class Object
        Returns:
        the formatted string
      • meta

        public static FxRate.Meta meta()
        The meta-bean for FxRate.
        Returns:
        the meta-bean, not null
      • metaBean

        public FxRate.Meta metaBean()
        Specified by:
        metaBean in interface org.joda.beans.Bean
      • getPair

        public CurrencyPair getPair()
        Gets the currency pair. The pair is formed of two parts, the base and the counter. In the pair 'AAA/BBB' the base is 'AAA' and the counter is 'BBB'.
        Returns:
        the value of the property, not null
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object