Package com.opengamma.strata.basics.currency

Class FxMatrix

  • All Implemented Interfaces:
    FxRateProvider, Serializable, org.joda.beans.Bean, org.joda.beans.ImmutableBean
    public final class FxMatrix
extends Object
implements FxRateProvider, org.joda.beans.ImmutableBean, Serializable
    A matrix of foreign exchange rates.

    This provides a matrix of foreign exchange rates, such that the rate can be queried for any available pair. For example, if the matrix contains the currencies 'USD', 'EUR' and 'GBP', then six rates can be queried, 'EUR/USD', 'GBP/USD', 'EUR/GBP' and the three inverse rates.

    This class is immutable and thread-safe.

    See Also:
    Serialized Form

    • Method Detail

      • empty

        public static FxMatrix empty()
        Obtains an empty FX matrix.

        The result contains no currencies or rates.

        Returns:
        an empty matrix

      • of

        public static FxMatrix of​(CurrencyPair currencyPair,
                          double rate)
        Obtains an instance containing a single FX rate.

        This is most likely to be used in testing.

        An invocation of the method with FxMatrix.of(CurrencyPair.of(GBP, USD), 1.6) indicates that 1 pound sterling is worth 1.6 US dollars. The matrix can also be queried for the reverse rate, from USD to GBP.

        Parameters:
        currencyPair - the currency pair to be added
        rate - the FX rate between the base currency of the pair and the counter currency. The rate indicates the value of one unit of the base currency in terms of the counter currency.
        Returns:
        a matrix containing the single FX rate

      • of

        public static FxMatrix of​(Currency ccy1,
                          Currency ccy2,
                          double rate)
        Obtains an instance containing a single FX rate.

        This is most likely to be used in testing.

        An invocation of the method with FxMatrix.of(GBP, USD, 1.6) indicates that 1 pound sterling is worth 1.6 US dollars. The matrix can also be queried for the reverse rate, from USD to GBP.

        Parameters:
        ccy1 - the first currency of the pair
        ccy2 - the second currency of the pair
        rate - the FX rate between the first currency and the second currency. The rate indicates the value of one unit of the first currency in terms of the second currency.
        Returns:
        a matrix containing the single FX rate

      • builder

        public static FxMatrixBuilder builder()
        Creates a builder that can be used to build instances of FxMatrix.
        Returns:
        a new builder

      • entriesToFxMatrix

        public static Collector<? super Map.Entry<CurrencyPair,​Double>,​FxMatrixBuilder,​FxMatrix> entriesToFxMatrix()
        Creates a Collector that allows a Map.Entry of currency pair to rate to be streamed and collected into a new FxMatrix.
        Returns:
        a collector for creating an FxMatrix from a stream

      • pairsToFxMatrix

        public static Collector<? super Pair<CurrencyPair,​Double>,​FxMatrixBuilder,​FxMatrix> pairsToFxMatrix()
        Creates a Collector that allows a collection of pairs each containing a currency pair and a rate to be streamed and collected into a new FxMatrix.
        Returns:
        a collector for creating an FxMatrix from a stream

      • getCurrencies

        public ImmutableSet<Currency> getCurrencies()
        Returns the set of currencies held within this matrix.
        Returns:
        the currencies in this matrix

      • 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).

        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

      • convert

        public CurrencyAmount convert​(CurrencyAmount amount,
                              Currency targetCurrency)
        Converts a CurrencyAmount into an amount in the specified currency using the rates in this matrix.
        Parameters:
        amount - the CurrencyAmount to be converted
        targetCurrency - the currency to convert the CurrencyAmount to
        Returns:
        the amount converted to the requested currency

      • convert

        public CurrencyAmount convert​(MultiCurrencyAmount amount,
                              Currency targetCurrency)
        Converts a MultipleCurrencyAmount into an amount in the specified currency using the rates in this matrix.
        Parameters:
        amount - the MultipleCurrencyAmount to be converted
        targetCurrency - the currency to convert all entries to
        Returns:
        the total amount in the requested currency

      • merge

        public FxMatrix merge​(FxMatrix other)
        Merges the entries from the other matrix into this one.

        The other matrix should have at least one currency in common with this one. The additional currencies from the other matrix are added one by one and the exchange rate data created is coherent with some data in this matrix.

        Note that if the other matrix has more than one currency in common with this one, and the rates for pairs of those currencies are different to the equivalents in this matrix, then the rates between the additional currencies is this matrix will differ from those in the original.

        Parameters:
        other - the matrix to be merged into this one
        Returns:
        a new matrix containing the rates from this matrix plus any rates for additional currencies from the other matrix

      • toBuilder

        public FxMatrixBuilder toBuilder()
        Creates a new builder using the data from this matrix to create a set of initial entries.
        Returns:
        a new builder containing the data from this matrix

      • meta

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

      • metaBean

        public FxMatrix.Meta metaBean()
        Specified by:
        metaBean in interface org.joda.beans.Bean

      • getRates

        public DoubleMatrix getRates()
        Gets the matrix with all the exchange rates. Each row represents the rates required to convert a unit of particular currency to all other currencies in the matrix.

        If currencies c1 and c2 are assigned indexes i and j respectively in the currencies map, then the entry [i][j] is such that 1 unit of currency c1 is worth rates[i][j] units of currency c2.

        If currencies.get(EUR) = 0 and currencies.get(USD) = 1, then the element rates[0][1] is likely to be around 1.40 and rates[1][0] around 0.7142. The rate rates[1][0] will be computed from fxRate[0][1] when the object is constructed by the builder. All the element of the matrix are meaningful and coherent.

        Returns:
        the value of the property, not null

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object