Follow ISO 80000-3

Author: josevalim

lib/elixir/lib/calendar/datetime.ex

@@ -1030,9 +1030,12 @@ defmodule DateTime do
   By default, `DateTime.to_iso8601/2` returns datetimes formatted in the "extended"
   format, for human readability. It also supports the "basic" format through passing the `:basic` option.
 
-  Only supports converting datetimes which are in the ISO calendar,
-  attempting to convert datetimes from other calendars will raise.
   You can also optionally specify an offset for the formatted string.
+  If none is given, the one in the given `datetime` is used.
+
+  Only supports converting datetimes which are in the ISO calendar.
+  If another calendar is given, it is automatically converted to ISO.
+  It raises if not possible.
 
   WARNING: the ISO 8601 datetime format does not contain the time zone nor
   its abbreviation, which means information is lost when converting to such
@@ -1346,6 +1349,11 @@ defmodule DateTime do
   @doc """
   Converts the given `datetime` to a string according to its calendar.
 
+  Unfortunately, there is no standard that specifies rendering of a
+  datetime with its complete time zone information, so Elixir uses a
+  custom (but relatively common) representation which appends the time
+  zone abbreviation and full name to the datetime.
+
   ### Examples
 
       iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",

lib/elixir/lib/calendar/duration.ex

@@ -358,76 +358,109 @@ defmodule Duration do
   @doc """
   Converts the given `duration` to a human readable representation.
 
+  ## Options
+
+    * `:units` - the units to be used alongside each duration component.
+      The default units follow the ISO 80000-3 standard:
+
+          [
+            year: "a",
+            month: "mo",
+            week: "wk",
+            day: "d",
+            hour: "h",
+            minute: "min",
+            second: "s"
+          ]
+
+    * `:separator` - how to separate the distinct components
+
   ## 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"
+      "30s"
+      iex> Duration.to_string(Duration.new!(day: 40, hour: 12, minute: 42, second: 12))
+      "40d 12h 42min 12s"
+
+  By default, this function uses ISO 80000-3 units, which uses "a" for years.
+  But you can customize all units via the units option:
+
+      iex> Duration.to_string(Duration.new!(year: 3))
+      "3a"
+      iex> Duration.to_string(Duration.new!(year: 3), units: [year: "y"])
+      "3y"
+
+  You may also choose the separator:
+
+      iex> Duration.to_string(Duration.new!(day: 40, hour: 12, minute: 42, second: 12), separator: ", ")
+      "40d, 12h, 42min, 12s"
+
+  A duration without components is rendered as "0s":
 
       iex> Duration.to_string(Duration.new!([]))
-      "0 seconds"
+      "0s"
+
+  Microseconds are rendered as part of seconds with the appropriate precision:
 
       iex> Duration.to_string(Duration.new!(second: 1, microsecond: {2_200, 3}))
-      "1.002 seconds"
+      "1.002s"
       iex> Duration.to_string(Duration.new!(second: 1, microsecond: {-1_200_000, 4}))
-      "-0.2000 seconds"
+      "-0.2000s"
 
   """
   @doc since: "1.18.0"
-  def to_string(%Duration{} = duration) do
-    case to_string_year(duration, []) do
+  def to_string(%Duration{} = duration, opts \\ []) do
+    units = Keyword.get(opts, :units, [])
+    separator = Keyword.get(opts, :separator, " ")
+
+    case to_string_year(duration, [], units) do
       [] ->
-        "0 seconds"
+        "0" <> Keyword.get(units, :second, "s")
 
       [part] ->
         IO.iodata_to_binary(part)
 
       parts ->
-        parts |> Enum.reduce(&[&1, ", " | &2]) |> IO.iodata_to_binary()
+        parts |> Enum.reduce(&[&1, separator | &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_part(0, _units, _key, _default, acc),
+    do: 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_part(x, units, key, default, acc),
+    do: [[Integer.to_string(x) | Keyword.get(units, key, default)] | acc]
 
-  defp to_string_month(%{month: month} = duration, acc) do
-    to_string_week(duration, to_string_part(month, " month", " months", acc))
+  defp to_string_year(%{year: year} = duration, acc, units) do
+    to_string_month(duration, to_string_part(year, units, :year, "a", acc), units)
   end
 
-  defp to_string_week(%{week: week} = duration, acc) do
-    to_string_day(duration, to_string_part(week, " week", " weeks", acc))
+  defp to_string_month(%{month: month} = duration, acc, units) do
+    to_string_week(duration, to_string_part(month, units, :month, "mo", acc), units)
   end
 
-  defp to_string_day(%{day: day} = duration, acc) do
-    to_string_hour(duration, to_string_part(day, " day", " days", acc))
+  defp to_string_week(%{week: week} = duration, acc, units) do
+    to_string_day(duration, to_string_part(week, units, :week, "wk", acc), units)
   end
 
-  defp to_string_hour(%{hour: hour} = duration, acc) do
-    to_string_minute(duration, to_string_part(hour, " hour", " hours", acc))
+  defp to_string_day(%{day: day} = duration, acc, units) do
+    to_string_hour(duration, to_string_part(day, units, :day, "d", acc), units)
   end
 
-  defp to_string_minute(%{minute: minute} = duration, acc) do
-    to_string_second(duration, to_string_part(minute, " minute", " minutes", acc))
+  defp to_string_hour(%{hour: hour} = duration, acc, units) do
+    to_string_minute(duration, to_string_part(hour, units, :hour, "h", acc), units)
   end
 
-  defp to_string_second(%{second: 1, microsecond: {0, _}}, acc) do
-    ["1 second" | acc]
+  defp to_string_minute(%{minute: minute} = duration, acc, units) do
+    to_string_second(duration, to_string_part(minute, units, :minute, "min", acc), units)
   end
 
-  defp to_string_second(%{second: 0, microsecond: {0, _}}, acc) do
+  defp to_string_second(%{second: 0, microsecond: {0, _}}, acc, _units) do
     acc
   end
 
-  defp to_string_second(%{second: s, microsecond: {ms, p}}, acc) do
-    [[second_component(s, ms, p) | " seconds"] | acc]
+  defp to_string_second(%{second: s, microsecond: {ms, p}}, acc, units) do
+    [[second_component(s, ms, p) | Keyword.get(units, :second, "s")] | acc]
   end
 
   @doc """

lib/elixir/lib/calendar/naive_datetime.ex

@@ -759,6 +759,9 @@ defmodule NaiveDateTime do
   @doc """
   Converts the given naive datetime to a string according to its calendar.
 
+  For redability, this function follows the RFC3339 suggestion of removing
+  the "T" separator between the date and time components.
+
   ### Examples
 
       iex> NaiveDateTime.to_string(~N[2000-02-28 23:00:13])

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

@@ -361,66 +361,72 @@ defmodule DurationTest do
 
   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"
+             "1a 2mo 3d 4h 5min 6s"
 
     assert Duration.to_string(%Duration{week: 3, hour: 5, minute: 3}) ==
-             "3 weeks, 5 hours, 3 minutes"
+             "3wk 5h 3min"
 
     assert Duration.to_string(%Duration{hour: 5, minute: 3}) ==
-             "5 hours, 3 minutes"
+             "5h 3min"
 
     assert Duration.to_string(%Duration{year: 1, month: 2, day: 3}) ==
-             "1 year, 2 months, 3 days"
+             "1a 2mo 3d"
 
     assert Duration.to_string(%Duration{hour: 4, minute: 5, second: 6}) ==
-             "4 hours, 5 minutes, 6 seconds"
+             "4h 5min 6s"
 
     assert Duration.to_string(%Duration{year: 1, month: 2}) ==
-             "1 year, 2 months"
+             "1a 2mo"
 
     assert Duration.to_string(%Duration{day: 3}) ==
-             "3 days"
+             "3d"
 
     assert Duration.to_string(%Duration{hour: 4, minute: 5}) ==
-             "4 hours, 5 minutes"
+             "4h 5min"
 
     assert Duration.to_string(%Duration{second: 6}) ==
-             "6 seconds"
+             "6s"
 
     assert Duration.to_string(%Duration{second: 1, microsecond: {600_000, 1}}) ==
-             "1.6 seconds"
+             "1.6s"
 
     assert Duration.to_string(%Duration{second: -1, microsecond: {-600_000, 1}}) ==
-             "-1.6 seconds"
+             "-1.6s"
 
     assert Duration.to_string(%Duration{second: -1, microsecond: {-234_567, 6}}) ==
-             "-1.234567 seconds"
+             "-1.234567s"
 
     assert Duration.to_string(%Duration{second: 1, microsecond: {123_456, 6}}) ==
-             "1.123456 seconds"
+             "1.123456s"
 
     assert Duration.to_string(%Duration{year: 3, week: 4, day: -3, second: -6}) ==
-             "3 years, 4 weeks, -3 days, -6 seconds"
+             "3a 4wk -3d -6s"
 
     assert Duration.to_string(%Duration{second: -4, microsecond: {-230_000, 2}}) ==
-             "-4.23 seconds"
+             "-4.23s"
 
     assert Duration.to_string(%Duration{second: -4, microsecond: {230_000, 2}}) ==
-             "-3.77 seconds"
+             "-3.77s"
 
     assert Duration.to_string(%Duration{second: 2, microsecond: {-1_200_000, 4}}) ==
-             "0.8000 seconds"
+             "0.8000s"
 
     assert Duration.to_string(%Duration{second: 1, microsecond: {-1_200_000, 3}}) ==
-             "-0.200 seconds"
+             "-0.200s"
 
     assert Duration.to_string(%Duration{microsecond: {-800_000, 2}}) ==
-             "-0.80 seconds"
+             "-0.80s"
 
     assert Duration.to_string(%Duration{microsecond: {-800_000, 0}}) ==
-             "0 seconds"
+             "0s"
 
     assert Duration.to_string(%Duration{microsecond: {-1_200_000, 2}}) ==
-             "-1.20 seconds"
+             "-1.20s"
+
+    assert Duration.to_string(%Duration{year: 1, month: 2, day: 3, hour: 4, minute: 5, second: 6},
+             units: [year: "year", month: "month", day: "day"],
+             separator: "-"
+           ) ==
+             "1year-2month-3day-4h-5min-6s"
   end
 end