Class CurrencyPair

  • All Implemented Interfaces:
    java.io.Serializable

    public final class CurrencyPair
    extends java.lang.Object
    implements java.io.Serializable
    An ordered pair of currencies, such as 'EUR/USD'.

    This could be used to identify a pair of currencies for quoting rates in FX deals. See FxRate for the representation that contains a rate.

    It is recommended to define currencies in advance using the CurrencyPair.ini file. Standard configuration includes many commonly used currency pairs.

    Only currencies listed in configuration will be returned by getAvailablePairs(). If a pair is requested that is not defined in configuration, it will still be created, however the market convention information will be generated.

    This class is immutable and thread-safe.

    See Also:
    Serialized Form
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean contains​(Currency currency)
      Checks if the currency pair contains the supplied currency as either its base or counter.
      java.util.Optional<CurrencyPair> cross​(CurrencyPair other)
      Finds the currency pair that is a cross between this pair and the other pair.
      boolean equals​(java.lang.Object obj)
      Checks if this currency pair equals another.
      static java.util.Set<CurrencyPair> getAvailablePairs()
      Obtains the set of configured currency pairs.
      Currency getBase()
      Gets the base currency of the pair.
      Currency getCounter()
      Gets the counter currency of the pair.
      int getRateDigits()
      Gets the number of digits in the rate.
      int hashCode()
      Returns a suitable hash code for the currency.
      CurrencyPair inverse()
      Gets the inverse currency pair.
      boolean isConventional()
      Checks if this currency pair is a conventional currency pair.
      boolean isIdentity()
      Checks if this currency pair is an identity pair.
      boolean isInverse​(CurrencyPair other)
      Checks if this currency pair is the inverse of the specified pair.
      static CurrencyPair of​(Currency base, Currency counter)
      Obtains an instance from two currencies.
      Currency other​(Currency currency)
      Finds the other currency in the pair.
      static CurrencyPair parse​(java.lang.String pairStr)
      Parses a currency pair from a string with format AAA/BBB.
      CurrencyPair toConventional()
      Returns the market convention currency pair for the currencies in the pair.
      com.google.common.collect.ImmutableSet<Currency> toSet()
      Returns the set of currencies contains in the pair.
      java.lang.String toString()
      Returns the formatted string version of the currency pair.
      • Methods inherited from class java.lang.Object

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

      • getAvailablePairs

        public static java.util.Set<CurrencyPair> getAvailablePairs()
        Obtains the set of configured currency pairs.

        This contains all the currency pairs that have been defined in configuration. Any currency pair instances that have been dynamically created are not included.

        Returns:
        an immutable set containing all registered currency pairs
      • of

        public static CurrencyPair of​(Currency base,
                                      Currency counter)
        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.

        Parameters:
        base - the base currency
        counter - the counter currency
        Returns:
        the currency pair
      • parse

        public static CurrencyPair parse​(java.lang.String pairStr)
        Parses a currency pair from a string with format AAA/BBB.

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

        Parameters:
        pairStr - the currency pair as a string AAA/BBB
        Returns:
        the currency pair
        Throws:
        java.lang.IllegalArgumentException - if the pair cannot be parsed
      • inverse

        public CurrencyPair inverse()
        Gets the inverse currency pair.

        The inverse pair has the same currencies but in reverse order.

        Returns:
        the inverse pair
      • contains

        public boolean contains​(Currency currency)
        Checks if the currency pair contains the supplied currency as either its base or counter.
        Parameters:
        currency - the currency to check against the pair
        Returns:
        true if the currency is either the base or counter currency in the pair
      • other

        public Currency other​(Currency currency)
        Finds the other currency in the pair.

        If the pair is AAA/BBB, then passing in AAA will return BBB, and passing in BBB will return AAA. Passing in CCC will throw an exception.

        Parameters:
        currency - the currency to check
        Returns:
        the other currency in the pair
        Throws:
        java.lang.IllegalArgumentException - if the specified currency is not one of those in the pair
      • isIdentity

        public boolean isIdentity()
        Checks if this currency pair is an identity pair.

        The identity pair is one where the base and counter currency are the same..

        Returns:
        true if this pair is an identity pair
      • isInverse

        public boolean isInverse​(CurrencyPair other)
        Checks if this currency pair is the inverse of the specified pair.

        This could be used to check if an FX rate specified in one currency pair needs inverting.

        Parameters:
        other - the other currency pair
        Returns:
        true if the currency is the inverse of the specified pair
      • cross

        public java.util.Optional<CurrencyPair> cross​(CurrencyPair other)
        Finds the currency pair that is a cross between this pair and the other pair.

        The cross is only returned if the two pairs contains three currencies in total, such as AAA/BBB and BBB/CCC and neither pair is an identity such as AAA/AAA.

        • Given two pairs AAA/BBB and BBB/CCC the result will be AAA/CCC or CCC/AAA as per the market convention.
        • Given two pairs AAA/BBB and CCC/DDD the result will be empty.
        • Given two pairs AAA/AAA and AAA/BBB the result will be empty.
        • Given two pairs AAA/BBB and AAA/BBB the result will be empty.
        • Given two pairs AAA/AAA and AAA/AAA the result will be empty.
        Parameters:
        other - the other currency pair
        Returns:
        the cross currency pair, or empty if no cross currency pair can be created
      • isConventional

        public boolean isConventional()
        Checks if this currency pair is a conventional currency pair.

        A market convention determines that 'EUR/USD' should be used and not 'USD/EUR'. This knowledge is encoded in configuration for a standard set of pairs.

        It is possible to create two different currency pairs from any two currencies, and it is guaranteed that exactly one of the pairs will be the market convention pair.

        If a currency pair is not explicitly listed in the configuration, a priority ordering of currencies is used to choose base currency of the pair that is treated as conventional.

        If there is no configuration available to determine which pair is the market convention, a pair will be chosen arbitrarily but deterministically. This ensures the same pair will be chosen for any two currencies even if the CurrencyPair instances are created independently.

        Returns:
        true if the currency pair follows the market convention, false if it does not
      • toConventional

        public CurrencyPair toConventional()
        Returns the market convention currency pair for the currencies in the pair.

        If isConventional() is true this method returns this, otherwise it returns the inverse() pair.

        Returns:
        the market convention currency pair for the currencies in the pair
      • toSet

        public com.google.common.collect.ImmutableSet<Currency> toSet()
        Returns the set of currencies contains in the pair.
        Returns:
        the set of currencies, with iteration in conventional order
      • getRateDigits

        public int getRateDigits()
        Gets the number of digits in the rate.

        If this rate is a conventional currency pair defined in configuration, then the number of digits in a market FX rate quote is returned.

        If the currency pair is not defined in configuration the sum of the minor unit digits from the two currencies is returned.

        Returns:
        the number of digits in the FX rate
      • getBase

        public Currency getBase()
        Gets the base currency of the pair.

        In the pair 'AAA/BBB' the base is 'AAA'.

        Returns:
        the base currency
      • getCounter

        public Currency getCounter()
        Gets the counter currency of the pair.

        In the pair 'AAA/BBB' the counter is 'BBB'.

        The counter currency is also known as the quote currency or the variable currency.

        Returns:
        the counter currency
      • equals

        public boolean equals​(java.lang.Object obj)
        Checks if this currency pair equals another.

        The comparison checks the two currencies.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the other currency pair, 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()
        Returns the formatted string version of the currency pair.

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

        Overrides:
        toString in class java.lang.Object
        Returns:
        the formatted string