exchange 0.8.0 → 0.9.0

data/.gitignore

@@ -13,6 +13,7 @@ doc
 
 # bundler
 .bundle
+*.rdb
 
 # filestore
 exchange_filestore

data/.rspec

@@ -1,2 +1,2 @@
 --color
---format documentation
+--format progress

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    exchange (0.7.6)
+    exchange (0.9.0)
       json (>= 1.0.0)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    dalli (2.2.1)
+    dalli (2.3.0)
     diff-lcs (1.1.3)
     json (1.7.5)
     nokogiri (1.5.5)
@@ -21,7 +21,7 @@ GEM
     rspec-expectations (2.11.3)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.11.3)
-    yard (0.8.2.1)
+    yard (0.8.3)
 
 PLATFORMS
   java

data/README.rdoc

@@ -4,6 +4,16 @@ The Exchange Gem gives you easy access to currency functions directly on your Nu
 
 You can use it with just plain ruby projects, in Rails 2 and 3, Sinatra or whatever Framework you like.
 
+== Installation
+=== Bundler / Rails
+Add it to your Gemfile  
+  gem "exchange", ">=0.8.0"
+=== Manually
+Just install it as a gem
+  gem install exchange
+Then require it
+  require 'exchange'
+
 == Features
 
 === Easy Conversion
@@ -12,6 +22,63 @@ Conversion of currencies does not get any easier
   1.eur.to_usd
 or better for historic dates
   1.eur.to_usd(:at => Time.now - 84600)
+  
+  
+=== Precise Calculation
+
+You may know the deal: Floating Point Errors can cost you money:
+  
+  (0.29 * 50).round #=> 14, which is incorrect
+
+Whereas
+
+  (BigDecimal("0.29") * 50).round #=> 15, which is correct
+  
+Exchange uses BigDecimal in all its currency and conversion operations, so you will not be a likely victim for floating point inaccuracies. It even does implicitly convert counterparts of basic operations like (* / - +) to calculate your values safely:
+
+  (50.usd * 0.29).round 0 #=> "USD 15.00"
+  (0.29 * 50.usd).round 0 #=> 15
+  
+=== BigDecimal? Sounds slow to me
+
+If performance combined with conversion is your concern, {head over to this benchmark}[https://github.com/beatrichartz/exchange/blob/master/benchmark/benchmark.rb]. With ruby 1.9.3, you'll get about the following results
+
+  1000 operations
+
+  Normal Float Operation takes 	0.000196s
+  Big Decimal Operation takes 	0.001239s
+  Money gem Operation takes 	0.05348s
+  Exchange gem Operation takes 	0.035287s
+
+You're right that Big Decimal is slower than Float operations, but then again, the exchange gem outscores the money gem.
+  
+=== A mixin for typecasting
+
+There may be a need for you to typecast an attribute of an object as money. Exchange features a typecasting mixin, which you can use with Rails, Ohm, Datamapper, or just plain ruby classes to typecast an attribute as money. Use it like this:
+
+  class Article
+    # make the class method available
+    #
+    extend Exchange::Typecasting
+    
+    # Install the typecasting for price
+    #
+    money :price, :currency => :currency
+    
+    # let's say you have currency set in a unique place
+    #
+    def currency
+      manager.currency
+    end
+  end
+  
+Now you're able to do this:
+  
+  article = Article.new
+  article.price #=> will give you money in the currency defined on the manager
+  article.price = 3.45.usd #Will implicitly convert the price if manager.currency is not :usd
+  
+You can feed the currency option with a proc or a symbol representing the method. For in-depth information about typecasting {visit the documentation here}[http://rubydoc.info/github/beatrichartz/exchange/Exchange/Typecasting]
 
 === Only one request per day to keep you up to date
 
@@ -21,11 +88,9 @@ You're hitting the internet only daily to get new rates (hourly updates are avai
 On of the issues with currencies is: You never know the format they should be in. With Exchange, you can just use the currencies
 to_s method, which takes care of the right format for you. You can either have a string with the currency code in front, or just the amount in the right format
 
-  Exchange::Currency.new(49.567, :usd).to_s           #=> "USD 49.57"
-  Exchange::Currency.new(45, :jpy).to_s               #=> "JPY 45"
-  Exchange::Currency.new(34.34, :omr).to_s            #=> "OMR 34.340"
-  Exchange::ISO4217.stringif(34.34, :omr).to_s(:iso)  #=> "34.340"
-
+  49.567.usd.to_s           #=> "USD 49.57"
+  45.jpy.to_s               #=> "JPY 45"
+  34.34.omr.to_s            #=> "OMR 34.340"
 
 === Use three great APIs or your own
 
@@ -33,7 +98,7 @@ Three open APIs are already included:
 
 - {Xaviermedia}[http://www.xavierforum.com/viewtopic.php?f=5&t=10979&sid=671a685edbfa5dbec219fbc6793d5057]
 - {European Central Bank}[http://www.ecb.int/stats/exchange/eurofxref/html/index.en.html]
-- {Currency Bot}[http://currencybot.github.com/]
+- {Open Exchange Rates}[http://openexchangerates.org/] (Look for the free plan at the bottom of the page)
 
 but if you have another API you like to use, it becomes as easy as writing one Class and two methods to use it. 
 {Example of a custom API Extension}[http://rubydoc.info/github/beatrichartz/exchange/Exchange/ExternalAPI]
@@ -49,41 +114,31 @@ Use one of three available caching solutions:
 But, same here, if you don't like any of these or want to use your own caching solution, it is as easy as writing one Class and two methods to use it. 
 {Example of a custom cache extension}[http://rubydoc.info/github/beatrichartz/exchange/Exchange/Cache]
 
-== Installation
-=== Bundler / Rails
-Add it to your Gemfile  
-  gem "exchange", ">=0.7.3"
-=== Manually
-Just install it as a gem
-  gem install exchange
-Then require it
-  require 'exchange'
-
 == Basic Operations
 
 === Convert
 
 Converting one currency to another is as easy as 1,2,3. Don't be afraid, even if it returns a currency object, all Fixed and Float operations can be applied as method missing routes to the value
 
-  1.usd.to_eur                                  #=> #<Exchange::Currency @value=0.93 @currency=:eur>
-  2.3.dkk.to_sek                                #=> #<Exchange::Currency @value=3.33 @currency=:sek>
-  45.54.nok.to_sek                              #=> #<Exchange::Currency @value=3.33 @currency=:sek>
+  1.usd.to_eur                                  #=> #<Exchange::Money @value=0.93 @currency=:eur>
+  2.3.dkk.to_sek                                #=> #<Exchange::Money @value=3.33 @currency=:sek>
+  45.54.nok.to_sek                              #=> #<Exchange::Money @value=3.33 @currency=:sek>
 
 Easily convert one currency to another at a historical rate
 
-  1.52.usd.to_eur :at => '2011-01-01'           #=> #<Exchange::Currency @value=1.23 @currency=:eur>
-  3.45.eur.to_sek :at => Time.gm(2011,3,3)      #=> #<Exchange::Currency @value=19.23 @currency=:sek>
-  345.sek.to_nok :at => Time.gm(2011,3,3)       #=> #<Exchange::Currency @value=348 @currency=:nok>
+  1.52.usd.to_eur :at => '2011-01-01'           #=> #<Exchange::Money @value=1.23 @currency=:eur>
+  3.45.eur.to_sek :at => Time.gm(2011,3,3)      #=> #<Exchange::Money @value=19.23 @currency=:sek>
+  345.sek.to_nok :at => Time.gm(2011,3,3)       #=> #<Exchange::Money @value=348 @currency=:nok>
   
 Or even define an instance of currency as historic by adding a time.
 
-  1.52.usd(:at => '2011-01-01').to_eur          #=> #<Exchange::Currency @value=1.23 @currency=:eur>
-  3.45.eur(:at => Time.gm(2011,3,3)).to_sek     #=> #<Exchange::Currency @value=19.23 @currency=:sek>
-  345.sek(:at => Time.gm(2011,3,3)).to_nok      #=> #<Exchange::Currency @value=348 @currency=:nok>
+  1.52.usd(:at => '2011-01-01').to_eur          #=> #<Exchange::Money @value=1.23 @currency=:eur>
+  3.45.eur(:at => Time.gm(2011,3,3)).to_sek     #=> #<Exchange::Money @value=19.23 @currency=:sek>
+  345.sek(:at => Time.gm(2011,3,3)).to_nok      #=> #<Exchange::Money @value=348 @currency=:nok>
   
 Do multiple conversion steps at once (if in any way useful)
 
-  3.chf.to_eur(:at => '2011-02-04').to_usd      #=> #<Exchange::Currency @value=5.3 @currency=:eur>
+  3.chf.to_eur(:at => '2011-02-04').to_usd      #=> #<Exchange::Money @value=5.3 @currency=:eur>
   
   
 === Compare
@@ -99,49 +154,54 @@ Compare Currencies, they will convert implicitly
 
 Sort multiple currencies at once
 
-  [5.eur, 4.usd, 4.chf(:at => '2010-01-01')].sort   #=> [#<Exchange::Currency @value=4 @currency=:usd>, #<Exchange::Currency @value=4 @currency=:chf>, #<Exchange::Currency @value=5 @currency=:eur>]
+  [5.eur, 4.usd, 4.chf(:at => '2010-01-01')].sort   #=> [#<Exchange::Money @value=4 @currency=:usd>, #<Exchange::Money @value=4 @currency=:chf>, #<Exchange::Money @value=5 @currency=:eur>]
   
 This is true, because it uses the same historic conversion rate
 
   3.eur(:at => '201-01-01').to_usd == 3.eur.to_usd(:at => '201-01-01')
   
-But this is false, obviously, because the second instance uses the present exchange rate
+But this is false, obviously, because the second instance uses the present exchange rate which differs from the historic one (if the two rates match, this will be true again)
 
-  3.eur(:at => '201-01-01').to_usd == 3.eur.to_usd
+  3.eur(:at => '2001-01-01').to_usd == 3.eur.to_usd
   
 === Operate
 
 Add, Subtract, Multiply, Divide Currencies and don't lose a dime. The result will get returned in the currency of the first argument
 
-  1.usd + 1.32.eur                              #=> #<Exchange::Currency @value=2.54 @currency=:usd>
-  1.usd - 1.32.eur                              #=> #<Exchange::Currency @value=-0.2 @currency=:usd>
-  1.usd * 1.32.eur                              #=> #<Exchange::Currency @value=3.44 @currency=:usd>
-  1.usd / 1.32.eur                              #=> #<Exchange::Currency @value=0.89 @currency=:usd>
+  1.usd + 1.32.eur                              #=> #<Exchange::Money @value=2.54 @currency=:usd>
+  1.usd - 1.32.eur                              #=> #<Exchange::Money @value=-0.2 @currency=:usd>
+  1.usd * 1.32.eur                              #=> #<Exchange::Money @value=3.44 @currency=:usd>
+  1.usd / 1.32.eur                              #=> #<Exchange::Money @value=0.89 @currency=:usd>
   
   
 If you define a currency object as historic. It will use historic conversion if it gets converted (in this example, the 1.32 eur will get converted to usd at the rate of January 1 2008)
 
-  1.usd - 1.32.eur(:at => '2008-1-1')           #=> #<Exchange::Currency @value=2.54 @currency=:usd>
+  1.usd - 1.32.eur(:at => '2008-1-1')           #=> #<Exchange::Money @value=2.54 @currency=:usd>
+
+You can just instantiate currencies and apply operations. Rounding will by default round the currency to its ISO4217 decimal precision:
 
-You can just instantiate currencies and apply operations
+  3.123.eur.round                               #=> #<Exchange::Money @value=3.12 @currency=:eur>
+  
+You can also pass the precision you wish for as an argument, round, ceil, floor act like normal:
 
-  3.1.eur.round                                   #=> #<Exchange::Currency @value=3 @currency=:eur>
+  3.1234.eur.round(0)                           #=> #<Exchange::Money @value=3 @currency=:eur>
 
 Convert one currency to another and round, ceil or floor it, it still retains currency information of the actual and previous currency
 
-  1.34.usd.to_eur.round                         #=> #<Exchange::Currency @value=1 @currency=:eur>
-  10.34.usd.to_nok.ceil                         #=> #<Exchange::Currency @value=45 @currency=:nok>
-  5.34.usd.to_eur.floor                         #=> #<Exchange::Currency @value=4 @currency=:eur>
-  5.34.usd.to_eur.floor.from                    #=> #<Exchange::Currency @value=5.34 @currency=:usd>
+  1.34.usd.to_eur.round(0)                      #=> #<Exchange::Money @value=1 @currency=:eur>
+  10.34.usd.to_nok.ceil(0)                      #=> #<Exchange::Money @value=45 @currency=:nok>
+  5.34.usd.to_eur.floor(0)                      #=> #<Exchange::Money @value=4 @currency=:eur>
+  5.34.usd.to_eur.floor.from                    #=> #<Exchange::Money @value=5.34 @currency=:usd>
   
   
 === Retain Information
 
 Access the original currency and its value after conversion, even over multiple steps
-  converted = 2.eur.to_usd                      #=> #<Exchange::Currency @value=2.12 @currency=:usd>
-  converted.from                                #=> #<Exchange::Currency @value=2 @currency=:eur>
-  converted2 = converted.to_nok                 #=> #<Exchange::Currency @value=22.12 @currency=:nok>
-  converted2.from                               #=> #<Exchange::Currency @value=2.12 @currency=:usd>
+
+  converted = 2.eur.to_usd                      #=> #<Exchange::Money @value=2.12 @currency=:usd>
+  converted.from                                #=> #<Exchange::Money @value=2 @currency=:eur>
+  converted2 = converted.to_nok                 #=> #<Exchange::Money @value=22.12 @currency=:nok>
+  converted2.from                               #=> #<Exchange::Money @value=2.12 @currency=:usd>
 
 == Configuration
 
@@ -157,7 +217,7 @@ You can configure the exchange gem to a variety of options, allowing you to cont
 The options available are
   
   :cache                                    Takes the cache options as a hash, the options are:
-    :subclass (default :memcached)          The cache subclass to use for caching. Available: Rails cache, Redis, Memcached, Filecache
+    :subclass (default :memory)             The cache subclass to use for caching. Available: Memory, Rails cache, Redis, Memcached, File
     :host (default '127.0.0.1')             A string with the hostname or IP to set the cache host to. Does not have to be set for Rails cache
     :port (default 11211)                   An integer for the cache port. Does not have to be set for Rails cache
     :expire (default :daily)                Which period is used to expire the cache, :daily or :hourly are available
@@ -166,6 +226,7 @@ The options available are
     :subclass (default :xavier_media)         The api to use. Available: Xavier Media, ECB, Currency Bot
     :retries (default 5)                      The number of times the gem should retry to connect to the api host
     :app_id (default nil)                     The app id to use with your api request
+    :protocol (default :http)                 The protocol to use with the request
     
   :allow_mixed_opterations (default true)   If set to false, Operations with with different currencies raise errors.
 
@@ -209,10 +270,17 @@ Use the Xaviermedia API as the source of your conversion rates
     }
   end
 
-Use the currencybot Open Source API as a source of your conversion rates
+Use the open exchange rates Open Source API as a source of your conversion rates
+  Exchange.configuration = Exchange::Configuration.new do |c|
+    c.api = {
+      :subclass => :open_exchange_rates
+    }
+  end
+  
+Use https as request protocol of your api requests:
   Exchange.configuration = Exchange::Configuration.new do |c|
     c.api = {
-      :subclass => :currency_bot
+      :protocol => :https
     }
   end
   

data/benchmark/benchmark.rb

@@ -0,0 +1,49 @@
+require 'benchmark'
+require 'bigdecimal'
+
+class Helper
+  def load_or_omit a_gem
+    begin
+      require a_gem.to_s
+      return true
+    rescue LoadError => e
+      puts "You do not have #{a_gem} installed. gem install #{a_gem} to benchmark it\n\n"
+      return false
+    end
+  end
+  
+  def median array
+    (array.inject(0) { |sum, member| sum += member } / 3.0).round 6 if array
+  end
+end
+
+helper = Helper.new
+
+operations = 1000
+results = {}
+
+results[:normal_float] = []
+3.times { results[:normal_float] << Benchmark.realtime { operations.times { 3.555 * 4.234 } } }
+
+results[:big_decimal] = []
+one = BigDecimal.new("3.555")
+two = BigDecimal.new("4.234")
+3.times { results[:big_decimal] << Benchmark.realtime { operations.times { one * two } } }
+
+if helper.load_or_omit(:money)
+  Money.add_rate("USD", "CAD", 1.24515)
+  results[:money] = []
+  3.times { results[:money] << Benchmark.realtime { operations.times { Money.us_dollar(50) * 0.29 } } }
+end
+
+if helper.load_or_omit(:exchange)
+  1.usd.to_cad #make the rate available in memory
+  results[:exchange] = []
+  3.times { results[:exchange] << Benchmark.realtime { operations.times { 50.usd * 0.29 } } }
+end
+
+puts "#{operations} operations\n\n"
+puts "Normal Float Operation takes \t#{helper.median(results[:normal_float])}s\n"
+puts "Big Decimal Operation takes \t#{helper.median(results[:big_decimal])}s\n"
+puts "Money gem Operation takes \t#{helper.median(results[:money])}s\n" if results[:money]
+puts "Exchange gem Operation takes \t#{helper.median(results[:exchange])}s\n" if results[:exchange]

data/changelog.rdoc

@@ -1,7 +1,14 @@
 = Changes to Exchange
 
-== 0.7.3
+== 0.9.0
+- added memory cache support as the new default. This allows you to cache without any external requirement, directly in ruby.
+- Added a typecasting helper for money to exchange. This allows you to typecast any given attribute into a instance of Exchange::Money
+- made the base operations more floating point error save. Now even when you use a float with exchange, it will convert it to bigdecimal before doing base calculations (* / + -) in both ways. This does not mean you will not encounter any floating point errors, but it makes it highly unlikely.
+- improved performance quite a bit on the conversion methods. Exchange now beats every other known gem for currency conversion in conversion speed
+
+== 0.8.0
 - jruby compatibility, horray!
+- readded json as an explicit dependency since its used in cache and api
 
 == 0.7.1
 - The DSL is now included into Numeric, which makes currency operations available for all subclasses (including your own) of Numeric

data/lib/exchange.rb

@@ -1,14 +1,14 @@
 require 'rubygems'
 require 'bigdecimal'
 require 'open-uri'
-require 'ostruct'
-require 'json'
 require 'exchange/base'
+require 'exchange/configurable'
 require 'exchange/gem_loader'
 require 'exchange/helper'
 require 'exchange/iso_4217'
-require 'exchange/currency'
+require 'exchange/money'
 require 'exchange/external_api'
 require 'exchange/cache'
 require 'exchange/configuration'
-require 'core_extensions/conversability'
+require 'exchange/core_extensions'
+require 'exchange/typecasting'

data/lib/exchange/base.rb

@@ -2,7 +2,7 @@ module Exchange
   
   # The current version of the exchange gem
   #
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
   
   # The root installation path of the gem
   # @version 0.5

data/lib/exchange/cache.rb

@@ -1,5 +1,7 @@
+require 'exchange/cache/configuration'
 require 'exchange/cache/base'
 require 'exchange/cache/memcached'
+require 'exchange/cache/memory'
 require 'exchange/cache/redis'
 require 'exchange/cache/rails'
 require 'exchange/cache/file'

data/lib/exchange/cache/base.rb

@@ -60,22 +60,36 @@ module Exchange
       
       # A Cache Key generator for the API Classes and the time
       # Generates a key which can handle expiration by itself
-      # @param [Exchange::ExternalAPI::Subclass] api_class The API to store the data for
-      # @param [optional, Time] time The time for which the data is valid
+      # @param [Exchange::ExternalAPI::Subclass] api The API to store the data for
+      # @param [Hash] opts The options for caching
       # @return [String] A string that can be used as cache key
       # @example
-      #   Exchange::Cache::Base.key(Exchange::ExternalAPI::CurrencyBot, Time.gm(2012,1,1)) #=> "Exchange_ExternalAPI_CurrencyBot_2012_1"
+      #   Exchange::Cache::Base.key(Exchange::ExternalAPI::OpenExchangeRates, Time.gm(2012,1,1)) #=> "Exchange_ExternalAPI_CurrencyBot_2012_1"
       #
       def key api, opts={}
-        time          = Exchange::Helper.assure_time(opts[:at], :default => :now)
-        [ 'exchange',
+        time          = helper.assure_time(opts[:at], :default => :now)
+        ['exchange',
           api.to_s, 
           time.year.to_s, 
           time.yday.to_s, 
-          Exchange.configuration.cache.expire == :hourly ? time.hour.to_s : nil,
+          config.expire == :hourly ? time.hour.to_s : nil,
           *(opts[:key_for] || [])
         ].compact.join('_')
       end
+      
+      # Convenience accessor to get to the cache configuration
+      # @return [Exchange::Cache::Configuration] the current cache configuration
+      #
+      def config
+        Exchange.configuration.cache
+      end
+      
+      # Convenience accessor for the helper
+      # @return [Exchange::Helper] the helper class
+      #
+      def helper
+        @helper ||= Exchange::Helper
+      end
         
     end