Add Money.Subscription.Plan.to_string/2. Addresses #186

Author: kipcole9

CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ## Money v5.21.0
 
+This is the changelog for Money v5.22.0 released on ______, 2025.  For older changelogs please consult the release tag on [GitHub](https://github.com/kipcole9/money/tags)
+
+### Enhancements
+
+* Adds `Money.Subscription.Plan.to_string/2` to return a localized string representation of a subscription plan. The implementation is conditional on [ex_cldr_units](https://hex.pm/packages/ex_cldr_units) being configured as a dependency in `mix.exs` and `Cldr.Unit` being added as a provider in the CLDR backend module. Thanks to @peaceful-james for the suggestion. Closes #186.
+
+## Money v5.21.0
+
 This is the changelog for Money v5.21.0 released on March 30th, 2025.  For older changelogs please consult the release tag on [GitHub](https://github.com/kipcole9/money/tags)
 
 ### Enhancements

lib/money/subscription/plan.ex

@@ -29,7 +29,7 @@ defmodule Money.Subscription.Plan do
   Returns `{:ok, Money.Subscription.Plan.t}` or an `{:error, reason}`
   tuple.
 
-  ## Arguments
+  ### Arguments
 
   * `:price` is any `Money.t`
 
@@ -39,11 +39,11 @@ defmodule Money.Subscription.Plan do
   * `:interval_count` is an integer count of the number of `:interval`s
     of the plan.  The default is `1`
 
-  ## Returns
+  ### Returns
 
   A `Money.Subscription.Plan.t`
 
-  ## Examples
+  ### Examples
 
       iex> Money.Subscription.Plan.new Money.new(:USD, 100), :month, 1
       {:ok,
@@ -93,7 +93,7 @@ defmodule Money.Subscription.Plan do
 
   Takes the same arguments as `Money.Subscription.Plan.new/3`.
 
-  ## Example
+  ##@ Example
 
       iex> Money.Subscription.Plan.new! Money.new(:USD, 100), :day, 30
       %Money.Subscription.Plan{
@@ -112,4 +112,68 @@ defmodule Money.Subscription.Plan do
       {:error, {exception, reason}} -> raise exception, reason
     end
   end
+
+  if Code.ensure_loaded?(Cldr.Unit) do
+    import Kernel, except: [to_string: 1]
+
+    @doc """
+    Return a localised string representation of a subscription
+    plan.
+
+    ### Arguments
+
+    * Any `Money.Subscription.Plan.t/1` as returned from
+      `Money.Subscription.Plan.new/3`.
+
+    * `options` is a keyword list of options.
+
+    ### Options
+
+    * See `Cldr.Unit.to_string/1` for available options.
+
+    ### Returns
+
+    * `{:ok, localized_string}` or
+
+    * `{:error, reason}`
+
+    ### Examples
+
+        iex> {:ok, plan} = Money.Subscription.Plan.new(Money.new(:USD, 10), :year)
+        iex> Money.Subscription.Plan.to_string(plan)
+        {:ok, "$10.00 per year"}
+        iex> Money.Subscription.Plan.to_string(plan, locale: :ja)
+        {:ok, "$10.00毎年"}
+        iex> Money.Subscription.Plan.to_string(plan, locale: :de, style: :narrow)
+        {:ok, "10,00\u00A0$/J"}
+
+        iex> {:ok, plan} = Money.Subscription.Plan.new(Money.new(:USD, 10), :day, 30)
+        iex> Money.Subscription.Plan.to_string(plan)
+        {:ok, "$10.00 per 30 days"}
+        iex> Money.Subscription.Plan.to_string(plan, locale: :de)
+        {:ok, "10,00\u00A0$ pro 30 Tage"}
+        iex> Money.Subscription.Plan.to_string(plan, locale: :de, style: :short)
+        {:ok, "10,00\u00A0$/30 Tg."}
+
+    """
+    @doc since: "5.22.0"
+    def to_string(%__MODULE__{} = plan, options \\ []) do
+      backend = Keyword.get_lazy(options, :backend, &Money.default_backend/0)
+
+      plan
+      |> unit_from_plan()
+      |> Cldr.Unit.new!(plan.price.amount)
+      |> Cldr.Unit.to_string(backend, options)
+    end
+
+    defp unit_from_plan(%__MODULE__{interval_count: 1} = plan) do
+      %{price: amount, interval: interval} = plan
+      "curr-#{amount.currency}-per-#{interval}"
+    end
+
+    defp unit_from_plan(%__MODULE__{interval_count: interval_count} = plan) do
+      %{price: amount, interval: interval} = plan
+      "curr-#{amount.currency}-per-#{interval_count}-#{interval}"
+    end
+  end
 end

mix.exs

@@ -1,7 +1,7 @@
 defmodule Money.Mixfile do
   use Mix.Project
 
-  @version "5.21.0"
+  @version "5.22.0"
 
   def project do
     [
@@ -93,6 +93,9 @@ defmodule Money.Mixfile do
     [
       {:ex_cldr_numbers, "~> 2.34"},
 
+      # Used for Money.Subscription.Plan.to_string/1
+      {:ex_cldr_units, "~> 3.19", optional: true},
+
       {:nimble_parsec, "~> 0.5 or ~> 1.0"},
       {:decimal, "~> 1.6 or ~> 2.0"},
       {:poison, "~> 3.0 or ~> 4.0 or ~> 5.0 or ~> 6.0", optional: true},

mix.lock

@@ -25,5 +25,5 @@ defmodule Money.Cldr do
       "ar-MA"
     ],
     default_locale: "en",
-    providers: [Cldr.Number, Money]
+    providers: [Cldr.Number, Cldr.Unit, Money]
 end

mix/test_cldr.ex

@@ -14,6 +14,7 @@ defmodule MoneyTest do
   doctest Money.ExchangeRates.Retriever
   doctest Money.Financial
   doctest Money.Sigil
+  doctest Money.Subscription.Plan
 
   test "create a new money struct with a binary currency code" do
     money = Money.new(1234, "USD")

test/money_test.exs

@@ -9,6 +9,6 @@ defmodule Money.DigitalToken.Test do
   end
 
   test "Formatting digital token" do
-    assert {:ok, "₿ 100.234235"} = Money.to_string(Money.new("BTC", "100.234235"))
+    assert {:ok, "₿100.234235"} = Money.to_string(Money.new("BTC", "100.234235"))
   end
 end

test/money_token_test.exs

@@ -19,6 +19,6 @@ defmodule Test.Cldr do
       "bn",
       "ar-MA"
     ],
-    providers: [Cldr.Number, Money],
+    providers: [Cldr.Number, Cldr.Unit, Money],
     suppress_warnings: true
 end