currency 0.3.3 → 0.4.0

data/lib/currency/currency_version.rb

@@ -1,6 +1,6 @@
+module Currency
+  CurrencyVersion = '0.4.0'
+end
 # DO NOT EDIT
 # This file is auto-generated by build scripts.
 # See:  rake update_version
-module Currency
-  CurrencyVersion = '0.3.3'
-end

data/lib/currency/exception.rb

@@ -1,14 +1,11 @@
-module Currency
-  module Exception
-  end
-end
-  
-# Base class for all Currency::Exception.
-class Currency::Exception::Base < Exception
-end
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+module Currency::Exception
+    # Base class for all Currency::Exception objects.
+    class Base < ::Exception
+    end
 
-module Currency
-  module Exception
     # Error during string parsing.
     class InvalidMoneyString < Base
     end
@@ -33,13 +30,16 @@ module Currency
     class UnknownCurrency < Base
     end
 
-    # Error if an Exchange cannot provide an Exchange::Rate.
+    # Error if an Exchange Rate Source cannot provide an Exchange::Rate.
     class UnknownRate < Base
     end
 
     # Error if an Exchange::Rate is not valid.
     class InvalidRate < Base
     end
-
-  end
-end
+    
+    # Error if a subclass is responsible for implementing a method.
+    class SubclassResponsibility < Base
+    end
+  
+end # module

data/lib/currency/exchange.rb

@@ -1,13 +1,14 @@
-# -*- ruby -*-
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+# The Currency::Exchange package is responsible for
+# the buying and selling of currencies.
 #
-# = Currency::Exchange
+# This feature is currently unimplemented.
 #
-# The Currency::Exchange package is responsible for
-# the conversion between currencies.
+# Exchange rate sources are configured via Currency::Exchange::Rate::Source.
 #
-
-module Currency
-module Exchange
+module Currency::Exchange
     @@default = nil
     @@current = nil
 
@@ -17,7 +18,7 @@ module Exchange
     # created.  Currency::Exchange::Base cannot service any
     # conversion rate requests.
     def self.default 
-      @@default ||= Base.new
+      @@default ||= raise("UNIMPLEMENTED")
     end
 
     # Sets the default Currency::Exchange object.
@@ -31,7 +32,7 @@ module Exchange
     # If #current= has not been called and #default= has not been called,
     # then UndefinedExchange is raised.
     def self.current
-      @@current || self.default || (raise Exception::UndefinedExchange.new("Currency::Exchange.current not defined"))
+      @@current || self.default || (raise ::Currency::Exception::UndefinedExchange.new("Currency::Exchange.current not defined"))
     end
 
     # Sets the current Currency::Exchange object used during
@@ -39,8 +40,9 @@ module Exchange
     def self.current=(x)
       @@current = x
     end
-end
-end
 
-require 'currency/exchange/base'
+end # module
+
 require 'currency/exchange/rate'
+require 'currency/exchange/rate/source'
+

data/lib/currency/exchange/rate.rb

@@ -1,40 +1,100 @@
-module Currency
-module Exchange
-  # Represents a convertion rate between two currencies
-  class Rate
-    def initialize(c1, c2, c1_to_c2_rate, source = "UNKNOWN", date = nil, recip = true)
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+# Represents a convertion rate between two currencies at a given period of time.
+class Currency::Exchange::Rate
+    # The first Currency.
+    attr_reader :c1
+
+    # The second Currency.
+    attr_reader :c2
+
+    # The rate between c1 and c2.
+    #
+    # To convert between m1 in c1 and m2 in c2:
+    #
+    #   m2 = m1 * rate.
+    attr_reader :rate
+
+    # The source of the rate.
+    attr_reader :source
+
+    # The Time of the rate.
+    attr_reader :date
+
+    # If the rate is derived from other rates, this describes from where it was derived.
+    attr_reader :derived
+
+    # Average rate over rate samples in a time range.
+    attr_reader :rate_avg
+    
+    # Number of rate samples used to calcuate _rate_avg_.
+    attr_reader :rate_samples
+
+    # The rate low between date_0 and date_1.
+    attr_reader :rate_lo
+
+    # The rate high between date_0 and date_1.
+    attr_reader :rate_hi
+
+    # The rate at date_0.
+    attr_reader :rate_date_0
+ 
+    # The rate at date_1.
+    attr_reader :rate_date_1
+    
+    # The lowest date of sampled rates.
+    attr_reader :date_0
+    
+    # The highest date of sampled rates.
+    # This is non-inclusive during searches to allow seamless tileings of 
+    # time with rate buckets.
+    attr_reader :date_1
+
+    def initialize(c1, c2, c1_to_c2_rate, source = "UNKNOWN", date = nil, derived = nil, reciprocal = nil, opts = nil)
       @c1 = c1
       @c2 = c2
       @rate = c1_to_c2_rate
-      raise Exception::InvalidRate.new(@rate) unless @rate > 0.0
+      raise ::Currency::Exception::InvalidRate.new(@rate) unless @rate && @rate >= 0.0
       @source = source
-      @date = date || Time.now
-      @reciprocal = recip
-    end
-
-    def c1
-      @c1
-    end
+      @date = date
+      @derived = derived
+      @reciprocal = reciprocal
 
-    def c2
-      @c2
+      if opts
+        opts.each_pair do | k, v |
+          self.instance_variable_set("@#{k}", v)
+        end
+      end
     end
 
-    def rate
-      @rate
-    end
 
-    def source
-      @source
+    # Returns a cached reciprocal Rate object from c2 to c1.
+    def reciprocal
+      @reciprocal ||= @rate == 1.0 ? self :
+        self.class.new(@c2, @c1, 
+                       1.0 / @rate, 
+                       @source, 
+                       @date, 
+                       "reciprocal(#{derived || "#{c1.code}#{c2.code}"})", self,
+                       { 
+                         :rate_avg     => @rate_avg    && 1.0 / @rate_avg,
+                         :rate_samples => @rate_samples,                            
+                         :rate_lo      => @rate_lo     && 1.0 / @rate_lo,
+                         :rate_hi      => @rate_hi     && 1.0 / @rate_hi,
+                         :rate_date_0  => @rate_date_0 && 1.0 / @rate_date_0,
+                         :rate_date_1  => @rate_date_1 && 1.0 / @rate_date_1,
+                         :date_0       => @date_0,
+                         :date_1       => @date_1,
+                       }
+                       )
     end
 
-    def date
-      @date
-    end
 
+    # Converts from _m_ in Currency _c1_ to the opposite currency.
     def convert(m, c1)
       m = m.to_f	
-      if ( @c1 == c1 )
+      if @c1 == c1
         # $stderr.puts "Converting #{@c1} #{m} to #{@c2} #{m * @rate} using #{@rate}"
         m * @rate
       else
@@ -42,10 +102,81 @@ module Exchange
         m / @rate
       end
     end
-  end
 
-  
-end # module
-end # module
+
+    # Collect rate samples into rate_avg, rate_hi, rate_lo, rate_0, rate_1, date_0, date_1.
+    def collect_rates(rates)
+      rates = [ rates ] unless rates.kind_of?(Enumerable)
+      rates.each do | r |
+        collect_rate(r)
+      end
+      self
+    end
+
+    # Collect rates samples in to this Rate.
+    def collect_rate(rate)
+      # Initial.
+      @rate_samples ||= 0
+      @rate_sum ||= 0
+      @src ||= rate
+      @c1 ||= rate.c1
+      @c2 ||= rate.c2
+      @date ||= rate.date
+      @src ||= rate.src
+
+      # Reciprocal?
+      if @c1 == rate.c2 && @c2 == rate.c1
+        collect_rate(rate.reciprocal)
+      elsif ! (@c1 == rate.c1 && @c2 == rate.c2)
+        raise("Cannot collect rates between different currency pairs")
+      else
+        # Multisource?
+        @src = "<<multiple-sources>>" unless @src == rate.source
+
+        # Calculate rate average.
+        @rate_samples += 1
+        @rate_sum += rate.rate || (rate.rate_lo + rate.rate_hi) * 0.5
+        @rate_avg = @rate_sum / @rate_samples
+
+        # Calculate rates ranges.
+        r = rate.rate_lo || rate.rate
+        unless @rate_lo && @rate_lo < r
+          @rate_lo = r
+        end
+        r = rate.rate_hi || rate.rate
+        unless @rate_hi && @rate_hi > r
+          @rate_hi = r
+        end
+
+        # Calculate rates on date range boundaries
+        r = rate.rate_date_0 || rate.rate
+        d = rate.date_0 || rate.date
+        unless @date_0 && @date_0 < d
+          @date_0 = d
+          @rate_0 = r
+        end
+
+        r = rate.rate_date_1 || rate.rate
+        d = rate.date_1 || rate.date
+        unless @date_1 && @date_1 > d
+          @date_1 = d 
+          @rate_0 = r
+        end
+
+        @date ||= rate.date || rate.date0 || rate.date1
+      end
+      self
+    end
+
+
+    def to_s(extended = false)
+      extended = "#{date_0} #{rate_0} |< #{rate_lo} #{rate} #{rate_hi} >| #{rate_1} #{date_1}" if extended
+      extended ||= ''
+      "#<#{self.class.name} #{c1.code} #{c2.code} #{rate} #{source.inspect} #{date ? date.strftime('%Y/%m/%d-%H:%M:%S') : 'nil'} #{derived && derived.inspect} #{extended}>"
+    end
+
+    def inspect; to_s; end
+
+end # class
 
 

data/lib/currency/exchange/rate/deriver.rb

@@ -0,0 +1,146 @@
+# Copyright (C) 2006-2007 Kurt Stephens <ruby-currency(at)umleta.com>
+# See LICENSE.txt for details.
+
+require 'currency/exchange/rate'
+require 'currency/exchange/rate/source/base'
+
+# The Currency::Exchange::Rate::Deriver class calculates derived rates
+# from base Rates from a rate Source by pivoting against a pivot currency or by
+# generating reciprocals.
+#
+class Currency::Exchange::Rate::Deriver < Currency::Exchange::Rate::Source::Base
+
+  # The source for base rates.
+  attr_accessor :source
+  
+
+  def name
+    source.name
+  end
+
+
+  def initialize(opt = { })
+    @source = nil
+    @pivot_currency = nil
+    @derived_rates = { }
+    @all_rates = { }
+    super
+  end 
+
+
+  def pivot_currency
+    @pivot_currency || @source.pivot_currency || :USD
+  end
+
+
+  # Return all currencies.
+  def currencies
+    @source.currencies
+  end
+
+
+  # Flush all cached Rates.
+  def clear_rates
+    @derived_rate.clear
+    @all_rates.clear
+    @source.clear
+    super
+  end
+ 
+
+  # Returns all combinations of rates except identity rates.
+  def rates(time = nil)
+    time = time && normalize_time(time)
+    all_rates(time)
+  end
+
+
+  # Computes all rates.
+  # time is assumed to be normalized.
+  def all_rates(time = nil)
+    if x = @all_rates["#{time}"]
+      return x 
+    end
+
+    x = @all_rates["#{time}"] = [ ]
+    
+    currencies = self.currencies
+
+    currencies.each do | c1 |
+      currencies.each do | c2 |
+        next if c1 == c2 
+        c1 = ::Currency::Currency.get(c1)
+        c2 = ::Currency::Currency.get(c2)
+        rate = rate(c1, c2, time)
+        x << rate
+      end
+    end
+
+    x
+  end
+
+
+  # Determines and creates the Rate between Currency c1 and c2.
+  #
+  # May attempt to use a pivot currency to bridge between
+  # rates.
+  #
+  def get_rate(c1, c2, time)
+    rate = get_rate_reciprocal(c1, c2, time)
+    
+    # Attempt to use pivot_currency to bridge
+    # between Rates.
+    unless rate
+      pc = ::Currency::Currency.get(pivot_currency)
+      
+      if pc &&
+          (rate_1 = get_rate_reciprocal(c1, pc, time)) && 
+          (rate_2 = get_rate_reciprocal(pc, c2, time))
+        c1_to_c2_rate = rate_1.rate * rate_2.rate
+        rate = new_rate(c1, c2, 
+                        c1_to_c2_rate, 
+                        rate_1.date || rate_2.date || time, 
+                        "pivot(#{pc.code},#{rate_1.derived || "#{rate_1.c1.code}#{rate_1.c2.code}"},#{rate_2.derived || "#{rate_2.c1}#{rate_2.c2}"})")
+      end
+    end
+    
+    rate
+  end
+
+
+  # Get a matching base rate or its reciprocal.
+  def get_rate_reciprocal(c1, c2, time)
+    rate = get_rate_base_cached(c1, c2, time)
+    unless rate
+      if rate = get_rate_base_cached(c2, c1, time)
+        rate = (@rate["#{c1}:#{c2}:#{time}"] ||= rate.reciprocal)
+      end
+    end
+    
+    rate
+  end
+
+
+  # Returns a cached base Rate.
+  #
+  def get_rate_base_cached(c1, c2, time)
+    rate = (@rate["#{c1}:#{c2}:#{time}"] ||= get_rate_base(c1, c2, time))
+    rate
+  end
+
+
+  # Returns a base Rate from the Source.
+  def get_rate_base(c1, c2, time)
+    if c1 == c2
+      # Identity rates are timeless.
+      new_rate(c1, c2, 1.0, nil, "identity")
+    else
+      source.rate(c1, c2, time)
+    end
+  end
+
+
+end # class
+
+  
+