RubyMoney - Money

To use the I18n gem for localized formatting (thousands separators, decimal marks, and symbol placement), set Money.locale_backend = :i18n. This relies on your translation files (e.g., en.yml) having the correct number.currency.format structure.

# Enable I18n localization
Money.locale_backend = :i18n

I18n.locale = :en
Money.from_cents(10_000_00, 'USD').format # => $10,000.00

I18n.locale = :es
Money.from_cents(10_000_00, 'USD').format # => $10.000,00

To use Money with specific locales (e.g., using the i18n gem for localization), configure the locale backend and available locales during your application setup.

require 'money'

# explicitly define locales
I18n.config.available_locales = :en
Money.locale_backend = :i18n

In Money 7.0, Money.default_currency changed from "USD" to nil. Initializing a Money object without a currency will now raise Currency::NoCurrency.

To restore the previous behavior or set a specific default, use an initializer:

# config/initializers/money.rb
Money.setup_defaults
Money.default_currency = Money::Currency.new("USD")

Alternatively, always specify the currency explicitly when creating objects:

Money.new(1_00, "USD")

In Money 6.0.0 and later, the Money#dollars and Money#amount methods return instances of BigDecimal instead of Float. This change was made to prevent precision errors associated with floating-point arithmetic.

To maintain compatibility, you should:

1. Recommended: Update your application logic to handle BigDecimal return values.
2. Fallback: If your application strictly requires a Float, call .to_f on the result of #dollars or #amount (e.g., money.amount.to_f).

When performing major version upgrades, refer to the specific migration guides for breaking changes and step-by-step instructions:

• Upgrading to 7.0: For migrating from 6.x to 7.0.
• Upgrading to 6.0: For upgrading to version 6.0.

You can install the stable release of the money gem using the standard Ruby gem command.

gem install money

Exchanging money is performed through an exchange bank object. By default, you must manually specify exchange rates using Money.add_rate. Once rates are defined, you can use exchange_to to convert a Money object to a different currency.

Money.add_rate("USD", "CAD", 1.24515)
Money.add_rate("CAD", "USD", 0.803115)

Money.us_dollar(100).exchange_to("CAD")  # => Money.from_cents(124, "CAD")
Money.ca_dollar(100).exchange_to("USD")  # => Money.from_cents(80, "USD")

To upgrade to Money 7.0, ensure your environment meets the following requirements:

• Ruby Version: Upgrade to Ruby 3.1 or later.
• i18n Version: Ensure you are using i18n ~> 1.9 in your Gemfile.

Testing your upgrade

1. Update your Gemfile to gem 'money', '~> 7.0'.
2. Run bundle update money.
3. Run your test suite (e.g., bundle exec rake test).
4. Check for deprecation warnings and review formatting/mathematical operation outputs.

# .ruby-version
3.1.0

# Gemfile
gem 'i18n', '~> 1.9'

bundle update money

The default rounding mode changed from BigDecimal::ROUND_HALF_EVEN (banker's rounding) to BigDecimal::ROUND_HALF_UP (standard rounding).

To maintain the old behavior (6.x), set the rounding mode explicitly in your initializer:

# config/initializers/money.rb
Money.rounding_mode = BigDecimal::ROUND_HALF_EVEN

The default locale backend changed from :legacy to :currency. The methods Money.use_i18n and Money.use_i18n= have been removed.

To use i18n-based formatting (the old default behavior), set the backend in your initializer:

# config/initializers/money.rb
Money.locale_backend = :i18n

To use the new default (currency-based formatting):

# config/initializers/money.rb
Money.locale_backend = :currency