Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 321 lines (240 sloc) 10.646 kb
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
1 # RubyMoney - Money
2
8f7d2a6 @semmons99 Update README.md
semmons99 authored
3 [![Gem Version](https://badge.fury.io/rb/money.png)](http://badge.fury.io/rb/money)
4 [![Build Status](https://travis-ci.org/RubyMoney/money.png?branch=master)](https://travis-ci.org/RubyMoney/money)
5 [![Code Climate](https://codeclimate.com/github/RubyMoney/money.png)](https://codeclimate.com/github/RubyMoney/money)
af54c22 @semmons99 Update README.md
semmons99 authored
6 [![Coverage Status](https://coveralls.io/repos/RubyMoney/money/badge.png?branch=master)](https://coveralls.io/r/RubyMoney/money?branch=master)
7597b08 @rrrene Update docs badge in README
rrrene authored
7 [![Inline docs](http://inch-ci.org/github/RubyMoney/money.png)](http://inch-ci.org/github/RubyMoney/money)
8f7d2a6 @semmons99 Update README.md
semmons99 authored
8 [![Dependency Status](https://gemnasium.com/RubyMoney/money.png)](https://gemnasium.com/RubyMoney/money)
9 [![License](http://img.shields.io/license/MIT.png?color=green)](http://opensource.org/licenses/MIT)
6d18d2d @semmons99 add build status from travis-ci to README
semmons99 authored
10
045dc63 @orien Update README.md
orien authored
11 :warning: Please read the [migration notes](#migration-notes) before upgrading to a new major version.
4ce547d @orien Update README.md
orien authored
12
118f3d0 @semmons99 Update README.md
semmons99 authored
13 If you miss String parsing, check out the new [monetize gem](https://github.com/RubyMoney/monetize).
14
c29746a @semmons99 Update README.md
semmons99 authored
15 ## Contributing
16
5d758f3 @semmons99 update README to point to contribution guidelines
semmons99 authored
17 See the [Contribution Guidelines](https://github.com/RubyMoney/money/blob/master/CONTRIBUTING.md)
c29746a @semmons99 Update README.md
semmons99 authored
18
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
19 ## Introduction
20
a481fa4 @semmons99 update documentation
semmons99 authored
21 A Ruby Library for dealing with money and currency conversion.
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
22
23 ### Features
24
25 - Provides a `Money` class which encapsulates all information about an certain
26 amount of money, such as its value and its currency.
27 - Provides a `Money::Currency` class which encapsulates all information about
28 a monetary unit.
29 - Represents monetary values as integers, in cents. This avoids floating point
30 rounding errors.
31 - Represents currency as `Money::Currency` instances providing an high level of
32 flexibility.
33 - Provides APIs for exchanging money from one currency to another.
34
35 ### Resources
36
22d1893 @semmons99 Update README.md
semmons99 authored
37 - [Website](http://rubymoney.github.com/money)
38 - [API Documentation](http://rubydoc.info/gems/money/frames)
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
39 - [Git Repository](http://github.com/RubyMoney/money)
40
5b147e5 @semmons99 add note about needing require json for JRUBY < 1.7.0
semmons99 authored
41 ### Notes
b128bec @semmons99 add note to README about UTF-8.
semmons99 authored
42
5b147e5 @semmons99 add note about needing require json for JRUBY < 1.7.0
semmons99 authored
43 - Your app must use UTF-8 to function with this library. There are a
44 number of non-ASCII currency attributes.
2eb0dca @bjones Add Ruby 1.8 support
bjones authored
45 - This app requires JSON. If you're using JRuby < 1.7.0
5b147e5 @semmons99 add note about needing require json for JRUBY < 1.7.0
semmons99 authored
46 you'll need to add `gem "json"` to your Gemfile or similar.
b128bec @semmons99 add note to README about UTF-8.
semmons99 authored
47
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
48 ## Downloading
49
50 Install stable releases with the following command:
51
52 gem install money
53
54 The development version (hosted on Github) can be installed with:
55
56 git clone git://github.com/RubyMoney/money.git
57 cd money
58 rake install
59
60 ## Usage
61
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
62 ``` ruby
63 require 'money'
64
65 # 10.00 USD
66 money = Money.new(1000, "USD")
67 money.cents #=> 1000
68 money.currency #=> Currency.new("USD")
69
70 # Comparisons
71 Money.new(1000, "USD") == Money.new(1000, "USD") #=> true
72 Money.new(1000, "USD") == Money.new(100, "USD") #=> false
73 Money.new(1000, "USD") == Money.new(1000, "EUR") #=> false
74 Money.new(1000, "USD") != Money.new(1000, "EUR") #=> true
75
76 # Arithmetic
77 Money.new(1000, "USD") + Money.new(500, "USD") == Money.new(1500, "USD")
78 Money.new(1000, "USD") - Money.new(200, "USD") == Money.new(800, "USD")
79 Money.new(1000, "USD") / 5 == Money.new(200, "USD")
80 Money.new(1000, "USD") * 5 == Money.new(5000, "USD")
81
c1fdab7 @epidemian Add Money.from_amount reference to README and CHANGELOG
epidemian authored
82 # Unit to subunit conversions
83 Money.from_amount(5, "USD") == Money.new(500, "USD") # 5 USD
84 Money.from_amount(5, "JPY") == Money.new(5, "JPY") # 5 JPY
85 Money.from_amount(5, "TND") == Money.new(5000, "TND") # 5 TND
86
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
87 # Currency conversions
88 some_code_to_setup_exchange_rates
89 Money.new(1000, "USD").exchange_to("EUR") == Money.new(some_value, "EUR")
90 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
91
92 ## Currency
93
94 Currencies are consistently represented as instances of `Money::Currency`.
95 The most part of `Money` APIs allows you to supply either a `String` or a
96 `Money::Currency`.
97
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
98 ``` ruby
99 Money.new(1000, "USD") == Money.new(1000, Currency.new("USD"))
100 Money.new(1000, "EUR").currency == Currency.new("EUR")
101 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
102
103 A `Money::Currency` instance holds all the information about the currency,
104 including the currency symbol, name and much more.
105
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
106 ``` ruby
107 currency = Money.new(1000, "USD").currency
108 currency.iso_code #=> "USD"
109 currency.name #=> "United States Dollar"
110 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
111
a83c2da @semmons99 Remove Money::Currency::TABLE. Add Money::Currency.register for adding
semmons99 authored
112 To define a new `Money::Currency` use `Money::Currency.register` as shown
113 below.
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
114
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
115 ``` ruby
a83c2da @semmons99 Remove Money::Currency::TABLE. Add Money::Currency.register for adding
semmons99 authored
116 curr = {
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
117 :priority => 1,
118 :iso_code => "USD",
19aa5a3 @alovak Update README.md
alovak authored
119 :iso_numeric => "840",
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
120 :name => "United States Dollar",
121 :symbol => "$",
20861bb @frankmt adding missing comma
frankmt authored
122 :subunit => "Cent",
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
123 :subunit_to_unit => 100,
124 :separator => ".",
125 :delimiter => ","
126 }
a83c2da @semmons99 Remove Money::Currency::TABLE. Add Money::Currency.register for adding
semmons99 authored
127
128 Money::Currency.register(curr)
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
129 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
130
131 The pre-defined set of attributes includes:
132
133 - `:priority` a numerical value you can use to sort/group the currency list
134 - `:iso_code` the international 3-letter code as defined by the ISO 4217 standard
19aa5a3 @alovak Update README.md
alovak authored
135 - `:iso_numeric` the international 3-digit code as defined by the ISO 4217 standard
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
136 - `:name` the currency name
137 - `:symbol` the currency symbol (UTF-8 encoded)
138 - `:subunit` the name of the fractional monetary unit
139 - `:subunit_to_unit` the proportion between the unit and the subunit
140 - `:separator` character between the whole and fraction amounts
141 - `:delimiter` character between each thousands place
142
cc8bb0e @georgemillo more helpful error message when trying to register
georgemillo authored
143 All attributes except `:iso_code` are optional. Some attributes, such as
144 `:symbol`, are used by the Money class to print out a representation of the
145 object. Other attributes, such as `:name` or `:priority`, exist to provide a
146 basic API you can take advantage of to build your application.
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
147
148 ### :priority
149
150 The priority attribute is an arbitrary numerical value you can assign to the
151 `Money::Currency` and use in sorting/grouping operation.
152
153 For instance, let's assume your Rails application needs to render a currency
154 selector like the one available
155 [here](http://finance.yahoo.com/currency-converter/). You can create a couple of
156 custom methods to return the list of major currencies and all currencies as
157 follows:
158
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
159 ``` ruby
160 # Returns an array of currency id where
161 # priority < 10
162 def major_currencies(hash)
163 hash.inject([]) do |array, (id, attributes)|
164 priority = attributes[:priority]
165 if priority && priority < 10
166 array[priority] ||= []
167 array[priority] << id
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
168 end
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
169 array
170 end.compact.flatten
171 end
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
172
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
173 # Returns an array of all currency id
174 def all_currencies(hash)
175 hash.keys
176 end
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
177
a83c2da @semmons99 Remove Money::Currency::TABLE. Add Money::Currency.register for adding
semmons99 authored
178 major_currencies(Money::Currency.table)
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
179 # => [ :usd, :eur, :bgp, :cad ]
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
180
a83c2da @semmons99 Remove Money::Currency::TABLE. Add Money::Currency.register for adding
semmons99 authored
181 all_currencies(Money::Currency.table)
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
182 # => [ :aed, :afn, all, ... ]
183 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
184
185 ### Default Currency
186
187 By default `Money` defaults to USD as its currency. This can be overwritten
188 using:
189
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
190 ``` ruby
191 Money.default_currency = Money::Currency.new("CAD")
192 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
193
194 If you use Rails, then `environment.rb` is a very good place to put this.
195
b9f04d4 @ct-clearhaus Add information regarding exponent to README.md
ct-clearhaus authored
196 ### Currency Exponent
197
198 The exponent of a money value is the number of digits after the decimal
199 separator (which separates the major unit from the minor unit). See e.g.
200 [Wikipedia on ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) for more
201 information. You can find the exponent (as a `Float`) by
202
203 ``` ruby
204 Money::Currency.new("USD").exponent # => 2.0
205 Money::Currency.new("JPY").exponent # => 0.0
206 Money::Currency.new("MGA").exponent # => 0.6989700043360189
207 ```
208
c51f899 @ct-clearhaus Update README and CHANGELOG.
ct-clearhaus authored
209 ### Currency Lookup
210
211 To find a given currency by ISO 4217 numeric code (three digits) you can do
212
213 ``` ruby
6680454 @ct-clearhaus Fix naming of find_by_iso_numeric in README.
ct-clearhaus authored
214 Money::Currency.find_by_iso_numeric(978) #=> Money::Currency.new(:eur)
c51f899 @ct-clearhaus Update README and CHANGELOG.
ct-clearhaus authored
215 ```
216
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
217 ## Currency Exchange
218
219 Exchanging money is performed through an exchange bank object. The default
220 exchange bank object requires one to manually specify the exchange rate. Here's
221 an example of how it works:
222
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
223 ``` ruby
224 Money.add_rate("USD", "CAD", 1.24515)
225 Money.add_rate("CAD", "USD", 0.803115)
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
226
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
227 Money.us_dollar(100).exchange_to("CAD") # => Money.new(124, "CAD")
228 Money.ca_dollar(100).exchange_to("USD") # => Money.new(80, "USD")
229 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
230
231 Comparison and arithmetic operations work as expected:
232
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
233 ``` ruby
234 Money.new(1000, "USD") <=> Money.new(900, "USD") # => 1; 9.00 USD is smaller
235 Money.new(1000, "EUR") + Money.new(10, "EUR") == Money.new(1010, "EUR")
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
236
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
237 Money.add_rate("USD", "EUR", 0.5)
238 Money.new(1000, "EUR") + Money.new(1000, "USD") == Money.new(1500, "EUR")
239 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
240
241 There is nothing stopping you from creating bank objects which scrapes
242 [XE](http://www.xe.com) for the current rates or just returns `rand(2)`:
243
aae1acd @phlipper add syntax highlighting to README for readability
phlipper authored
244 ``` ruby
245 Money.default_bank = ExchangeBankWhichScrapesXeDotCom.new
246 ```
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
247
6008ec1 @ohthatjames Update README and CHANGELOG
ohthatjames authored
248 If you wish to disable automatic currency conversion to prevent arithmetic when
249 currencies don't match:
250
251 ``` ruby
252 Money.disallow_currency_conversion!
253 ```
254
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
255 ### Implementations
256
257 The following is a list of Money.gem compatible currency exchange rate
258 implementations.
259
260 - [eu_central_bank](http://github.com/RubyMoney/eu_central_bank)
261 - [google_currency](http://github.com/RubyMoney/google_currency)
3683959 @matiaskorhonen Adds the nordea gem to the forex implementations list.
matiaskorhonen authored
262 - [nordea](https://github.com/k33l0r/nordea)
d2dab0a @slbug Added nbrb_currency to readme
slbug authored
263 - [nbrb_currency](https://github.com/slbug/nbrb_currency)
9d40356 @semmons99 add money-open-exchange-rates to README.md
semmons99 authored
264 - [money-open-exchange-rates](https://github.com/spk/money-open-exchange-rates)
577020a @semmons99 update money-historical-bank repo location in README.md
semmons99 authored
265 - [money-historical-bank](https://github.com/atwam/money-historical-bank)
70837d3 @rmustafin Add russian_central_bank to README
rmustafin authored
266 - [russian_central_bank](https://github.com/rmustafin/russian_central_bank)
7991ce5 @semmons99 reformat README using markdown
semmons99 authored
267
268 ## Ruby on Rails
269
8f77375 @semmons99 update RoR documentation to favor money-rails
semmons99 authored
270 To integrate money in a Rails application use [money-rails](http://github.com/RubyMoney/money-rails).
b372dcb @alup Update README.md with link to money-rails
alup authored
271
af8a98d @jc00ke Fix typo
jc00ke authored
272 For deprecated methods of integrating with Rails, check [the wiki](https://github.com/RubyMoney/money/wiki).
866fd11 @orien Migration notes listed in the README
orien authored
273
f00003f @alex-ross Adds documentations for I18n features
alex-ross authored
274 ## I18n
275
276 If you want thousands seperator and decimal mark to be same across all
277 currencies this can be defined in your `I18n` translation files.
278
279 In an rails application this may look like:
38e2248 @vandrijevik Fix typo in i18n example file
vandrijevik authored
280
f00003f @alex-ross Adds documentations for I18n features
alex-ross authored
281 ```yml
282 # config/locale/en.yml
283 en:
284 number:
285 format:
38e2248 @vandrijevik Fix typo in i18n example file
vandrijevik authored
286 delimiter: ","
0d52411 @Matsarello Typo fixes for I18n: seperator -> separator. Misunderstood typos fixed i...
Matsarello authored
287 separator: "."
f00003f @alex-ross Adds documentations for I18n features
alex-ross authored
288 # or
289 number:
290 currency:
291 format:
38e2248 @vandrijevik Fix typo in i18n example file
vandrijevik authored
292 delimiter: ","
0d52411 @Matsarello Typo fixes for I18n: seperator -> separator. Misunderstood typos fixed i...
Matsarello authored
293 separator: "."
f00003f @alex-ross Adds documentations for I18n features
alex-ross authored
294 ```
295
296 For this example `Money.new(123456789, "SEK").format` will return `1,234,567.89
297 kr` which otherwise will return `1 234 567,89 kr`.
298
299 If you wish to disable this feature:
300 ``` ruby
301 Money.use_i18n = false
302 ```
303
d2384d8 @mateusg Add Money.default_formatting_rules config hash
mateusg authored
304 *Note: There are several formatting rules for when `Money#format` is called. For more information, check out the [formatting module](https://github.com/RubyMoney/money/blob/master/lib/money/money/formatting.rb).*
305
866fd11 @orien Migration notes listed in the README
orien authored
306 ## Migration Notes
307
62ab346 @semmons99 version bump to 6.0.0
semmons99 authored
308 #### Version 6.0.0
866fd11 @orien Migration notes listed in the README
orien authored
309
310 - The `Money#dollars` and `Money#amount` methods now return instances of
311 `BigDecimal` rather than `Float`. We should avoid representing monetary
312 values with floating point types so to avoid a whole class of errors relating
313 to lack of precision. There are two migration options for this change:
314 * The first is to test your application and where applicable update the
315 application to accept a `BigDecimal` return value. This is the recommended
316 path.
317 * The second is to migrate from the `#amount` and `#dollars` methods to use
abc720f @orien Reallign documentation
orien authored
318 the `#to_f` method instead. This option should only be used where `Float`
319 is the desired type and nothing else will do for your application's
866fd11 @orien Migration notes listed in the README
orien authored
320 requirements.
Something went wrong with that request. Please try again.