Add a human readable representation of duration

lib/elixir/lib/calendar/duration.ex

@@ -355,6 +355,81 @@ defmodule Duration do
     end
   end
 
+  @doc """
+  Converts the given `duration` to a human readable representation.
+
+  ## Examples
+
+      iex> Duration.to_string(Duration.new!(year: 3))
+      "3 years"
+      iex> Duration.to_string(Duration.new!(day: 40, hour: 12, minute: 42, second: 12))
+      "40 days, 12 hours, 42 minutes, 12 seconds"
+      iex> Duration.to_string(Duration.new!(second: 30))
+      "30 seconds"
+
+      iex> Duration.to_string(Duration.new!([]))
+      "0 seconds"
+
+      iex> Duration.to_string(Duration.new!(second: 1, microsecond: {2_200, 3}))
+      "1.002 seconds"
+      iex> Duration.to_string(Duration.new!(second: 1, microsecond: {-1_200_000, 4}))
+      "-0.2000 seconds"
+
+  """
+  @doc since: "1.18.0"
+  def to_string(%Duration{} = duration) do
+    case to_string_year(duration, []) do
+      [] ->
+        "0 seconds"
+
+      [part] ->
+        IO.iodata_to_binary(part)
+
+      parts ->
+        parts |> Enum.reduce(&[&1, ", " | &2]) |> IO.iodata_to_binary()
+    end
+  end
+
+  defp to_string_part(0, _singular, _plural, acc), do: acc
+  defp to_string_part(1, singular, _plural, acc), do: [["1" | singular] | acc]
+  defp to_string_part(x, _singular, plural, acc), do: [[Integer.to_string(x) | plural] | acc]
+
+  defp to_string_year(%{year: year} = duration, acc) do
+    to_string_month(duration, to_string_part(year, " year", " years", acc))
+  end
+
+  defp to_string_month(%{month: month} = duration, acc) do
+    to_string_week(duration, to_string_part(month, " month", " months", acc))
+  end
+
+  defp to_string_week(%{week: week} = duration, acc) do
+    to_string_day(duration, to_string_part(week, " week", " weeks", acc))
+  end
+
+  defp to_string_day(%{day: day} = duration, acc) do
+    to_string_hour(duration, to_string_part(day, " day", " days", acc))
+  end
+
+  defp to_string_hour(%{hour: hour} = duration, acc) do
+    to_string_minute(duration, to_string_part(hour, " hour", " hours", acc))
+  end
+
+  defp to_string_minute(%{minute: minute} = duration, acc) do
+    to_string_second(duration, to_string_part(minute, " minute", " minutes", acc))
+  end
+
+  defp to_string_second(%{second: 1, microsecond: {0, _}}, acc) do
+    ["1 second" | acc]
+  end
+
+  defp to_string_second(%{second: 0, microsecond: {0, _}}, acc) do
+    acc
+  end
+
+  defp to_string_second(%{second: s, microsecond: {ms, p}}, acc) do
+    [[second_component(s, ms, p) | " seconds"] | acc]
+  end
+
   @doc """
   Converts the given `duration` to an [ISO 8601-2:2019](https://en.wikipedia.org/wiki/ISO_8601) formatted string.
 
@@ -407,15 +482,15 @@ defmodule Duration do
     []
   end
 
-  defp second_component(%{second: 0, microsecond: {_, 0}}) do
-    ~c"0S"
+  defp second_component(%{second: second, microsecond: {ms, p}}) do
+    [second_component(second, ms, p), ?S]
   end
 
-  defp second_component(%{second: second, microsecond: {_, 0}}) do
-    [Integer.to_string(second), ?S]
+  defp second_component(second, _ms, 0) do
+    Integer.to_string(second)
   end
 
-  defp second_component(%{second: second, microsecond: {ms, p}}) do
+  defp second_component(second, ms, p) do
     total_ms = second * @microseconds_per_second + ms
     second = total_ms |> div(@microseconds_per_second) |> abs()
     ms = total_ms |> rem(@microseconds_per_second) |> abs()
@@ -425,8 +500,7 @@ defmodule Duration do
       sign,
       Integer.to_string(second),
       ?.,
-      ms |> Integer.to_string() |> String.pad_leading(6, "0") |> binary_part(0, p),
-      ?S
+      ms |> Integer.to_string() |> String.pad_leading(6, "0") |> binary_part(0, p)
     ]
   end
 

lib/elixir/test/elixir/calendar/duration_test.exs

@@ -358,4 +358,69 @@ defmodule DurationTest do
     assert %Duration{microsecond: {-800_000, 0}} |> Duration.to_iso8601() == "PT0S"
     assert %Duration{microsecond: {-1_200_000, 2}} |> Duration.to_iso8601() == "PT-1.20S"
   end
+
+  test "to_string/1" do
+    assert Duration.to_string(%Duration{year: 1, month: 2, day: 3, hour: 4, minute: 5, second: 6}) ==
+             "1 year, 2 months, 3 days, 4 hours, 5 minutes, 6 seconds"
+
+    assert Duration.to_string(%Duration{week: 3, hour: 5, minute: 3}) ==
+             "3 weeks, 5 hours, 3 minutes"
+
+    assert Duration.to_string(%Duration{hour: 5, minute: 3}) ==
+             "5 hours, 3 minutes"
+
+    assert Duration.to_string(%Duration{year: 1, month: 2, day: 3}) ==
+             "1 year, 2 months, 3 days"
+
+    assert Duration.to_string(%Duration{hour: 4, minute: 5, second: 6}) ==
+             "4 hours, 5 minutes, 6 seconds"
+
+    assert Duration.to_string(%Duration{year: 1, month: 2}) ==
+             "1 year, 2 months"
+
+    assert Duration.to_string(%Duration{day: 3}) ==
+             "3 days"
+
+    assert Duration.to_string(%Duration{hour: 4, minute: 5}) ==
+             "4 hours, 5 minutes"
+
+    assert Duration.to_string(%Duration{second: 6}) ==
+             "6 seconds"
+
+    assert Duration.to_string(%Duration{second: 1, microsecond: {600_000, 1}}) ==
+             "1.6 seconds"
+
+    assert Duration.to_string(%Duration{second: -1, microsecond: {-600_000, 1}}) ==
+             "-1.6 seconds"
+
+    assert Duration.to_string(%Duration{second: -1, microsecond: {-234_567, 6}}) ==
+             "-1.234567 seconds"
+
+    assert Duration.to_string(%Duration{second: 1, microsecond: {123_456, 6}}) ==
+             "1.123456 seconds"
+
+    assert Duration.to_string(%Duration{year: 3, week: 4, day: -3, second: -6}) ==
+             "3 years, 4 weeks, -3 days, -6 seconds"
+
+    assert Duration.to_string(%Duration{second: -4, microsecond: {-230_000, 2}}) ==
+             "-4.23 seconds"
+
+    assert Duration.to_string(%Duration{second: -4, microsecond: {230_000, 2}}) ==
+             "-3.77 seconds"
+
+    assert Duration.to_string(%Duration{second: 2, microsecond: {-1_200_000, 4}}) ==
+             "0.8000 seconds"
+
+    assert Duration.to_string(%Duration{second: 1, microsecond: {-1_200_000, 3}}) ==
+             "-0.200 seconds"
+
+    assert Duration.to_string(%Duration{microsecond: {-800_000, 2}}) ==
+             "-0.80 seconds"
+
+    assert Duration.to_string(%Duration{microsecond: {-800_000, 0}}) ==
+             "0 seconds"
+
+    assert Duration.to_string(%Duration{microsecond: {-1_200_000, 2}}) ==
+             "-1.20 seconds"
+  end
 end