Add Kernel.to_timeout/1 (#13468)

Author: whatyouhide

lib/elixir/lib/kernel.ex

@@ -6093,6 +6093,150 @@ defmodule Kernel do
     Macro.compile_apply(mod, fun, [code, options, __CALLER__ | args], __CALLER__)
   end
 
+  hour_in_ms = 1000 * 60 * 60
+  day_in_ms = 24 * hour_in_ms
+  week_in_ms = 7 * day_in_ms
+
+  @doc """
+  Constructs a millisecond timeout from the given components, duration, or timeout.
+
+  This function is useful for constructing timeouts to use in functions that
+  expect `t:timeout/0` values (such as `Process.send_after/4` and many others).
+
+  ## Argument
+
+  The `duration` argument can be one of a `Duration`, a `t:timeout/0`, or a list
+  of components. Each of these is described below.
+
+  ### Passing `Duration`s
+
+  `t:Duration.t/0` structs can be converted to timeouts. The given duration must have
+  `year` and `month` fields set to `0`, since those cannot be reliably converted to
+  milliseconds (due to the varying number of days in a month and year).
+
+  Microseconds in durations are converted to milliseconds (through `System.convert_time_unit/3`).
+
+  ### Passing components
+
+  The `duration` argument can also be keyword list which can contain the following
+  keys, each appearing at most once with a non-negative integer value:
+
+    * `:week` - the number of weeks (a week is always 7 days)
+    * `:day` - the number of days (a day is always 24 hours)
+    * `:hour` - the number of hours
+    * `:minute` - the number of minutes
+    * `:second` - the number of seconds
+    * `:millisecond` - the number of milliseconds
+
+  The timeout is calculated as the sum of the components, each multiplied by
+  the corresponding factor.
+
+  ### Passing timeouts
+
+  You can also pass timeouts directly to this functions, that is, milliseconds or
+  the atom `:infinity`. In this case, this function just returns the given argument.
+
+  ## Examples
+
+  With a keyword list:
+
+      iex> to_timeout(hour: 1, minute: 30)
+      5400000
+
+  With a duration:
+
+      iex> to_timeout(%Duration{hour: 1, minute: 30})
+      5400000
+
+  With a timeout:
+
+      iex> to_timeout(5400000)
+      5400000
+      iex> to_timeout(:infinity)
+      :infinity
+
+  """
+  @doc since: "1.17.0"
+  @spec to_timeout([component, ...] | timeout() | Duration.t()) :: non_neg_integer()
+        when component: [{unit, non_neg_integer()}, ...],
+             unit: :week | :day | :hour | :minute | :second | :millisecond
+  def to_timeout(duration)
+
+  def to_timeout(:infinity), do: :infinity
+  def to_timeout(timeout) when is_integer(timeout) and timeout >= 0, do: timeout
+
+  def to_timeout(%{__struct__: Duration} = duration) do
+    case duration do
+      %{year: year} when year != 0 ->
+        raise ArgumentError,
+              "duration with a non-zero year cannot be reliably converted to timeouts"
+
+      %{month: month} when month != 0 ->
+        raise ArgumentError,
+              "duration with a non-zero month cannot be reliably converted to timeouts"
+
+      _other ->
+        {microsecond, _precision} = duration.microsecond
+        millisecond = :erlang.convert_time_unit(microsecond, :microsecond, :millisecond)
+
+        duration.week * unquote(week_in_ms) +
+          duration.day * unquote(day_in_ms) +
+          duration.hour * unquote(hour_in_ms) +
+          duration.minute * 60_000 +
+          duration.second * 1000 +
+          millisecond
+    end
+  end
+
+  def to_timeout(components) when is_list(components) do
+    reducer = fn
+      {key, value}, {acc, seen_keys} when is_integer(value) and value >= 0 ->
+        case :lists.member(key, seen_keys) do
+          true ->
+            raise ArgumentError, "timeout component #{inspect(key)} is duplicated"
+
+          false ->
+            :ok
+        end
+
+        factor =
+          case key do
+            :week ->
+              unquote(week_in_ms)
+
+            :day ->
+              unquote(day_in_ms)
+
+            :hour ->
+              unquote(hour_in_ms)
+
+            :minute ->
+              60_000
+
+            :second ->
+              1000
+
+            :millisecond ->
+              1
+
+            other ->
+              raise ArgumentError, """
+              timeout component #{inspect(other)} is not a valid timeout component, valid \
+              values are: :week, :day, :hour, :minute, :second, :millisecond\
+              """
+          end
+
+        {acc + value * factor, [key | seen_keys]}
+
+      {key, value}, {_acc, _seen_keys} ->
+        raise ArgumentError,
+              "timeout component #{inspect(key)} must be a non-negative " <>
+                "integer, got: #{inspect(value)}"
+    end
+
+    elem(:lists.foldl(reducer, {0, _seen_keys = []}, components), 0)
+  end
+
   ## Sigils
 
   @doc ~S"""

lib/elixir/test/elixir/kernel_test.exs

@@ -1500,4 +1500,73 @@ defmodule KernelTest do
       """)
     end
   end
+
+  describe "to_timeout/1" do
+    test "works with keyword lists" do
+      assert to_timeout(hour: 2) == 1000 * 60 * 60 * 2
+      assert to_timeout(minute: 74) == 1000 * 60 * 74
+      assert to_timeout(second: 1293) == 1_293_000
+      assert to_timeout(millisecond: 1_234_123) == 1_234_123
+
+      assert to_timeout(hour: 2, minute: 30) == 1000 * 60 * 60 * 2 + 1000 * 60 * 30
+      assert to_timeout(minute: 30, hour: 2) == 1000 * 60 * 60 * 2 + 1000 * 60 * 30
+      assert to_timeout(minute: 74, second: 30) == 1000 * 60 * 74 + 1000 * 30
+    end
+
+    test "raises on invalid values with keyword lists" do
+      for unit <- [:hour, :minute, :second, :millisecond],
+          value <- [-1, 1.0, :not_an_int] do
+        message =
+          "timeout component #{inspect(unit)} must be a non-negative integer, " <>
+            "got: #{inspect(value)}"
+
+        assert_raise ArgumentError, message, fn -> to_timeout([{unit, value}]) end
+      end
+    end
+
+    test "raises on invalid keys with keyword lists" do
+      message =
+        "timeout component :not_a_unit is not a valid timeout component, valid values are: " <>
+          ":week, :day, :hour, :minute, :second, :millisecond"
+
+      assert_raise ArgumentError, message, fn -> to_timeout(minute: 3, not_a_unit: 1) end
+    end
+
+    test "raises on duplicated components with keyword lists" do
+      assert_raise ArgumentError, "timeout component :minute is duplicated", fn ->
+        to_timeout(minute: 3, hour: 2, minute: 1)
+      end
+    end
+
+    test "works with durations" do
+      assert to_timeout(Duration.new!(hour: 2)) == 1000 * 60 * 60 * 2
+      assert to_timeout(Duration.new!(minute: 74)) == 1000 * 60 * 74
+      assert to_timeout(Duration.new!(second: 1293)) == 1_293_000
+      assert to_timeout(Duration.new!(microsecond: {1_234_123, 4})) == 1_234
+
+      assert to_timeout(Duration.new!(hour: 2, minute: 30)) == 1000 * 60 * 60 * 2 + 1000 * 60 * 30
+      assert to_timeout(Duration.new!(minute: 30, hour: 2)) == 1000 * 60 * 60 * 2 + 1000 * 60 * 30
+      assert to_timeout(Duration.new!(minute: 74, second: 30)) == 1000 * 60 * 74 + 1000 * 30
+    end
+
+    test "raises on durations with non-zero months or days" do
+      message = "duration with a non-zero month cannot be reliably converted to timeouts"
+
+      assert_raise ArgumentError, message, fn ->
+        to_timeout(Duration.new!(month: 3))
+      end
+
+      message = "duration with a non-zero year cannot be reliably converted to timeouts"
+
+      assert_raise ArgumentError, message, fn ->
+        to_timeout(Duration.new!(year: 1))
+      end
+    end
+
+    test "works with timeouts" do
+      assert to_timeout(1_000) == 1_000
+      assert to_timeout(0) == 0
+      assert to_timeout(:infinity) == :infinity
+    end
+  end
 end