<commit_before>= exchange {<img src="https://secure.travis-ci.org/beatrichartz/exchange.png" />}[http://travis-ci.org/beatrichartz/exchange] {<img src="https://gemnasium.com/beatrichartz/exchange.png" alt="Dependency Status" />}[https://gemnasium.com/beatrichartz/exchange] {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/beatrichartz/exchange]

The Exchange Gem gives you easy access to currency functions directly on your Numbers. {It is tested against}[http://travis-ci.org/beatrichartz/exchange]: ruby 1.9, ruby 1.8.7, ree, rubinius (1.8 and 1.9 mode) and jruby 

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.9.0"
=== Manually
Just install it as a gem
  gem install exchange
Then require it
  require 'exchange'

== Features

=== Easy Conversion

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

You're hitting the internet only daily to get new rates (hourly updates are available if you're eager to have the absolutely newest ones)

=== ISO 4217 Currency formatting
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

  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

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]
- {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]

=== Use great caches or your own great cache

Use one of three available caching solutions: 

- Memcached via the Dalli gem
- Redis via the redis gem
- Rails cache (This gem does however not depend on rails)

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. <commit_msg>! typo<commit_after>= exchange {<img src="https://secure.travis-ci.org/beatrichartz/exchange.png" />}[http://travis-ci.org/beatrichartz/exchange] {<img src="https://gemnasium.com/beatrichartz/exchange.png" alt="Dependency Status" />}[https://gemnasium.com/beatrichartz/exchange] {<img src="https://codeclimate.com/badge.png" />}[https://codeclimate.com/github/beatrichartz/exchange]

The Exchange Gem gives you easy access to currency functions directly on your Numbers. {It is tested against}[http://travis-ci.org/beatrichartz/exchange]: ruby 1.9, ruby 1.8.7, ree, rubinius (1.8 and 1.9 mode) and jruby 

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.9.0"
=== Manually
Just install it as a gem
  gem install exchange
Then require it
  require 'exchange'

== Features

=== Easy Conversion

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

You're hitting the internet only daily to get new rates (hourly updates are available if you're eager to have the absolutely newest ones)

=== ISO 4217 Currency formatting
One 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

  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

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]
- {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]

=== Use great caches or your own great cache

Use one of three available caching solutions: 

- Memcached via the Dalli gem
- Redis via the redis gem
- Rails cache (This gem does however not depend on rails)

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. 
{'fraction_non_alphanumeric': 0.08452307055659011, 'fraction_numerical': 0.028967515001034554, 'mean_word_length': 3.7110136452241713, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 31, 'https://': 12, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4644407', 'n_tokens_mistral': 3120, 'n_tokens_neox': 2815, 'n_words': 1237}