Changelog for Money v2.3.1

This is the changelog for Money v2.3.1 released on March 26th, 2018. For older changelogs please consult the release tag on GitHub

Enhancements

  • Clarify the examples of Money.to_string/2 to note that the default locale is “en-001”. Thanks to @snewcomer. Closes #61.

Changelog for Money v2.3.0

Bug Fixes

Enhancements

This version introduces a new module Money.Subscription that supports applications that manage subscriptions. These appications often need to support upgrading and downgrading plans. This action involves the calculation of a credit amount from the current plan that is then applied to the new plan. See Money.Subscription and Money.Subscription.change_plan/3.

Changelog for Money v2.2.2

This is the changelog for Money v2.2.2 released on February 27th, 2018. For older changelogs please consult the release tag on GitHub

Bug Fixes

  • Fix Money.split to ensure that split_amount * parts + remainder == original_money and added property testing

  • Allow Money.new/2 to have both a binary currency code and a binary amount. Thanks to @mbenatti. Closes #57.

Changelog for Money v2.2.1

Bug Fixes

  • Correctly round to cash increment Money.round/2 now correctly uses the rounding increment for a currency. This is relevant for currencies like :AUD and :CHF which have minimum cash rounding of 0.05 even though the accounting increment is 0.01. Thanks to @maennchen. Closes #56.

  • Update documentation for Money.round/2 to correctly refer to the option :currency_digits with the valid options of :cash, :accounting and :iso. The default is :iso. The option cash: true is invalid.

Changelog for Money v2.2.0

This release is primarily a refactoring of the exchange rates service. It separates the concerns of retrieval and caching. It also normalises the API amongst the three modules Money.ExchangeRates, Money.ExchangeRates.Retriever and Money.ExchangeRates.Cache. Each of these modules implements:

  • latest_rates/0
  • historic_rates/1

This makes it clear that rates can be retrieved through the cache or the service API. The implementation in Money.ExchangeRates will return the cached value if available or will call the service API if not.

Migration from earlier releases

The only known issue for migrating from earlier releases is if your application requires a different supervision strategy for the exchange rate service that the default one. This is documented in the README in the section “Using Ecto or other applications from within the callback module”. The change is the way in which the supervisor is defined. It is included here for completeness:

In prior releases:

supervisor(Money.ExchangeRates.Supervisor, [])

From this release onwards:

supervisor(Money.ExchangeRates.Supervisor, [[restart: true, start_retriever: true]])

Note that the option start_retriever: true is optional. The default is false. The option restart: true is required in this case because the exchange rates supervisor is always started when ex_money is started even if the retriever is not started. Therefore it needs to be stopped first before restarting in the new supervision tree. The option restart: true forces this step to be executed.

Enhancements

config :ex_money,
  exchange_rates_retrieve_every: :never
  • Use etag’s in the Money.ExchangeRates.OpenExchangeRates API module when retrieving exchange rates from the service.

  • Add Money.known_currencies/0 which delegates to Cldr.known_currencies/0 and returns the list of known currency codes

  • Add Money.known_current_currencies/0 to return the list of currencies currently active according to ISO 4217

  • Add Money.known_historic_currencies/0 to return a list of currencies known to Cldr but which are not considered in current use

  • Add Money.known_tender_currencies/0 to return a list of currencies defined as legal tender in Cldr

  • Add the configuration key :json_library that specifies which json library to use for decoding json. The default is Cldr.Config.json_library/0 which is currently Poison although this is likely to change to Jason when Phoenix makes this change.

  • Moves the protocol implementations for String.Chars, Inspect and Phoenix.HTML.Safe to a separate file so that recompilation on locale configuration change works correctly.

Changelog for Money v2.1.0

Enhancements

  • Money.to_integer_exp/2 now uses the definition of digits (subunits) as defined by ISO 4217. Previously the definition was that supplied by CLDR. CLDR’s definition is not always in alignment with ISO 4217. ISO 4217 is a firm requirement for financial transactions through payment gateways.

  • Bump dependencies for ex_cldr to 1.4.0 and ex_cldr_numbers to 1.3.0 to support :iso_digits

Changelog for Money v2.0.4

Bug Fixes

  • Fixed from_float!/2 which would fail since new/2 does not return {:ok, Money.t}. Note that from ex_money 3.0, Money.new/2 will return {:ok, Money.t} to be consistent with canonical approaches in Elixir. Closes #48. Thanks for @lostkobrakai.

Changelog for Money v2.0.3

Bug Fixes

  • Fixes the typespec for Money.new/2 and revises several other typespecs. Added a dialyzer configuration. Since Money.new/2 allows flexible (probably too flexible) order or arguments, the typespec does not fully match the function implementation and Dialyzer understandably complains. However the value of a typespec as documentation argues against making the typespec formally correct. This will be revisited for Money 3.0.

Changelog for Money v2.0.2

Bug Fixes

  • Money.Sigil was calling String.to_existing_atom/1 directly rather than Cldr.validate_currency/1. Since currency codes are only loaded and therefore the atoms materialized when Cldr is loaded this created a situation whereby a valid currency code may raise an agument error. Money.Sigil now correctly calls Cldr.validate_currency/1 which ensures the currency atoms are loaded before validation. Closes #46.

Changelog for Money v2.0.1

Bug Fixes

  • Phoenix.HTML.Safe protocol implementation correctly returns a formatted string, not an {:ok, string} tuple. Closes #45.

Changelog for Money v2.0.0

Breaking Changes

  • The function Money.new/2 no longer supports a float amount. The new function Money.from_float/2 is introduced. The factory function Money.new/2 previously supported a float amount as a parameter. There are many well-documented issues with float. Although a float with a precision of no more than 15 digits will convert (and round-trip) without loss of precision there is a real possibility that the upstream calculations that produced the float will have introduced rounding or precision errors. Calling Money.new/2 with a float amount will return an error tuple:
  {:error, {
    Money.InvalidAmountError,
      "Float amounts are not supported in new/2 due to potenial rounding " <>
      "and precision issues.  If absolutely required, use Money.from_float/2"}}

Enhancements

  • Add Money.from_float/2 to create a Money struct from a float and a currency code. This function is named to make it clear that we risk losing precision due to upstream rounding errors. According to the standard and experimentation, floats of up to 15 digits of precision will round trip without error. Therefore from_float/2 will check the precision of the number and return an error if the precision is greater than 15 since the correctness of the number cannot be verified beyond that.

  • Add Money.from_float!/2 which is like from_float/2 but raises on error

  • Formatted the text the with the Elixir 1.6 code formatter