Add Cldr.Currency.currency_for_code

elixir-cldr · Jun 4, 2022 · e5935c4 · e5935c4
1 parent e246cdc
commit e5935c4
Show file tree

Hide file tree

Showing 4 changed files with 155 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## Cldr_Currencies v2.14.0
+
+This is the changelog for Cldr_Currencies v2.14.0 released on June 4th, 2022.  For older changelogs please consult the release tag on [GitHub](https://github.com/elixir-cldr/cldr_currencies/tags)
+
+### Enhancements
+
+* Add `Cldr.Currency.currency_for_code/2` and the same function for backend modules.
+
 ## Cldr_Currencies v2.13.0
 
 This is the changelog for Cldr_Currencies v2.13.0 released on February 21st, 2022.  For older changelogs please consult the release tag on [GitHub](https://github.com/elixir-cldr/cldr_currencies/tags)

diff --git a/lib/cldr/backend.ex b/lib/cldr/backend.ex
@@ -255,6 +255,12 @@ defmodule Cldr.Currency.Backend do
         * `:locale` is any valid locale name returned by `Cldr.known_locale_names/1`
           or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`
 
+        ## Returns
+
+        * A `{:ok, currency}` or
+
+        * `{:error, {exception, reason}}`
+
         ## Examples
 
             iex> #{inspect(__MODULE__)}.currency_for_code("AUD")
@@ -300,6 +306,70 @@ defmodule Cldr.Currency.Backend do
           Cldr.Currency.currency_for_code(currency_or_currency_code, unquote(backend), options)
         end
 
+        @doc """
+        Returns the currency metadata for the requested currency code.
+
+        ## Arguments
+
+        * `currency_or_currency_code` is a `binary` or `atom` representation
+           of an ISO 4217 currency code, or a `%Cldr.Currency{}` struct.
+
+        ## Options
+
+        * `:locale` is any valid locale name returned by `Cldr.known_locale_names/1`
+          or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`
+
+        ## Returns
+
+        * A `t:Cldr.Current.t/0` or
+
+        * raises an exception
+
+        ## Examples
+
+            iex> #{inspect(__MODULE__)}.currency_for_code!("AUD")
+            %Cldr.Currency{
+              cash_digits: 2,
+              cash_rounding: 0,
+              code: "AUD",
+              count: %{one: "Australian dollar", other: "Australian dollars"},
+              digits: 2,
+              iso_digits: 2,
+              name: "Australian Dollar",
+              narrow_symbol: "$",
+              rounding: 0,
+              symbol: "A$",
+              tender: true
+            }
+
+            iex> #{inspect(__MODULE__)}.currency_for_code!("THB")
+            %Cldr.Currency{
+              cash_digits: 2,
+              cash_rounding: 0,
+              code: "THB",
+              count: %{one: "Thai baht", other: "Thai baht"},
+              digits: 2,
+              iso_digits: 2,
+              name: "Thai Baht",
+              narrow_symbol: "฿",
+              rounding: 0,
+              symbol: "THB",
+              tender: true
+            }
+
+        """
+        @doc since: "2.14.0"
+
+        @spec currency_for_code!(Cldr.Currency.code() | Cldr.Currency.t(), Keyword.t()) ::
+                Cldr.Currency.t() | no_return()
+
+        def currency_for_code!(
+              currency_or_currency_code,
+              options \\ [locale: unquote(backend).default_locale()]
+            ) do
+          Cldr.Currency.currency_for_code!(currency_or_currency_code, unquote(backend), options)
+        end
+
         defp get_currency_metadata(code, nil) do
           string_code = to_string(code)
 

diff --git a/lib/cldr/currency.ex b/lib/cldr/currency.ex
@@ -881,6 +881,12 @@ defmodule Cldr.Currency do
   * `:locale` is any valid locale name returned by `Cldr.known_locale_names/1`
     or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`
 
+  ## Returns
+
+  * A `{:ok, currency}` or
+
+  * `{:error, {exception, reason}}`
+
   ## Examples
 
       iex> Cldr.Currency.currency_for_code("AUD", MyApp.Cldr)
@@ -936,6 +942,75 @@ defmodule Cldr.Currency do
     end
   end
 
+  @doc """
+  Returns the currency metadata for the requested currency code.
+
+  ## Arguments
+
+  * `currency_or_currency_code` is a `binary` or `atom` representation
+      of an ISO 4217 currency code, or a `t:Cldr.Currency` struct.
+
+  * `backend` is any module that includes `use Cldr` and therefore
+    is a `Cldr` backend module
+
+  * `options` is a `Keyword` list of options.
+
+  ## Options
+
+  * `:locale` is any valid locale name returned by `Cldr.known_locale_names/1`
+    or a `Cldr.LanguageTag` struct returned by `Cldr.Locale.new!/2`
+
+  ## Returns
+
+  * A `t:Cldr.Current.t/0` or
+
+  * raises an exception
+
+  ## Examples
+
+      iex> Cldr.Currency.currency_for_code!("AUD", MyApp.Cldr)
+      %Cldr.Currency{
+        cash_digits: 2,
+        cash_rounding: 0,
+        code: "AUD",
+        count: %{one: "Australian dollar", other: "Australian dollars"},
+        digits: 2,
+        iso_digits: 2,
+        name: "Australian Dollar",
+        narrow_symbol: "$",
+        rounding: 0,
+        symbol: "A$",
+        tender: true
+      }
+
+      iex> Cldr.Currency.currency_for_code!("THB", MyApp.Cldr)
+      %Cldr.Currency{
+        cash_digits: 2,
+        cash_rounding: 0,
+        code: "THB",
+        count: %{one: "Thai baht", other: "Thai baht"},
+        digits: 2,
+        iso_digits: 2,
+        name: "Thai Baht",
+        narrow_symbol: "฿",
+        rounding: 0,
+        symbol: "THB",
+        tender: true
+      }
+
+  """
+  @doc since: "2.14.0"
+
+  @spec currency_for_code!(code() | t(), Cldr.backend(), Keyword.t()) ::
+          t() | no_return()
+
+  def currency_for_code!(currency_or_currency_code, backend, options \\ []) do
+    case currency_for_code(currency_or_currency_code, backend, options) do
+      {:ok, currency} -> currency
+      {:error, {exception, reason}} -> raise exception, reason
+    end
+  end
+
   @doc """
   Returns a map of the metadata for all currencies for
   a given locale.

diff --git a/mix.exs b/mix.exs
@@ -1,7 +1,7 @@
 defmodule Cldr.Currencies.MixProject do
   use Mix.Project
 
-  @version "2.13.0"
+  @version "2.14.0"
 
   def project do
     [
@@ -38,7 +38,7 @@ defmodule Cldr.Currencies.MixProject do
 
   defp deps do
     [
-      {:ex_cldr, "~> 2.24"},
+      {:ex_cldr, "~> 2.27"},
 
       {:jason, "~> 1.0", optional: true},
       {:ex_doc, "~> 0.18", only: [:dev, :release], runtime: false, optional: true},