Update Membrane.Time API

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.0.0
+ * Replace `Membrane.Time.round_to_<unit_name>/1` with `Membrane.Time.as_<unit_name>/2` with second argument equal `:round`. Rename `Membrane.Time.round_to_timebase/2` to `Membrane.Time.divide_by_timebase/2` [#494](https://github.com/membraneframework/membrane_core/pull/494)
+
 ## 0.11.0
  * Separate element_name and pad arguments in handle_element_{start, end}_of_stream signature [#219](https://github.com/membraneframework/membrane_core/issues/219)
  * Refine communication between parent and its children [#270](https://github.com/membraneframework/membrane_core/issues/270)

lib/membrane/core/timer.ex

@@ -62,7 +62,7 @@ defmodule Membrane.Core.Timer do
     beam_next_tick_time =
       Ratio.add(Ratio.new(init_time), Ratio.div(next_tick_time, ratio))
       |> Ratio.floor()
-      |> Time.round_to_milliseconds()
+      |> Time.as_milliseconds(:round)
 
     timer_ref =
       Process.send_after(self(), Message.new(:timer_tick, id), beam_next_tick_time, abs: true)

lib/membrane/sync.ex

@@ -186,7 +186,7 @@ defmodule Membrane.Sync do
     |> Enum.filter(&(&1.status == :sync))
     |> Enum.group_by(& &1.latency, & &1.reply_to)
     |> Enum.each(fn {latency, reply_to} ->
-      time = (max_latency - latency) |> Time.round_to_milliseconds()
+      time = (max_latency - latency) |> Time.as_milliseconds(:round)
       Process.send_after(self(), {:reply, reply_to}, time)
     end)
   end

lib/membrane/time.ex

@@ -229,16 +229,16 @@ defmodule Membrane.Time do
   end
 
   @doc """
-  Returns timestamp in timebase units. Rounded to the nearest integer.
+  Divides timestamp by timebase. Rounded to the nearest integer.
 
   ## Examples:
       iex> timestamp = 10 |> Membrane.Time.seconds()
       iex> timebase = Ratio.new(Membrane.Time.second(), 30)
-      iex> Membrane.Time.round_to_timebase(timestamp, timebase)
+      iex> Membrane.Time.divide_by_timebase(timestamp, timebase)
       300
   """
-  @spec round_to_timebase(number | Ratio.t(), number | Ratio.t()) :: integer
-  def round_to_timebase(timestamp, timebase) do
+  @spec divide_by_timebase(number | Ratio.t(), number | Ratio.t()) :: integer
+  def divide_by_timebase(timestamp, timebase) do
     Ratio.new(timestamp, timebase) |> round_rational()
   end
 
@@ -267,26 +267,21 @@ defmodule Membrane.Time do
       |> round_rational()
     end
 
-    round_to_fun_name = :"round_to_#{unit.plural}"
-
-    @doc """
-    Returns time in #{unit.plural}. Rounded to the nearest integer.
-    """
-    @spec unquote(round_to_fun_name)(t) :: integer
-    # credo:disable-for-next-line Credo.Check.Readability.Specs
-    def unquote(round_to_fun_name)(time) when is_time(time) do
-      Ratio.new(time, unquote(unit.duration)) |> round_rational()
-    end
-
     as_fun_name = :"as_#{unit.plural}"
 
     @doc """
-    Returns time in #{unit.plural}, represented as a rational number.
+    Returns time in #{unit.plural}. If second argument is not provided
+    or is equal to `:exact`, result is represented as a rational number.
+    If second argument is equal to `:round`, result is rounded to the
+    nearest integer.
     """
-    @spec unquote(as_fun_name)(t) :: integer | Ratio.t()
+    @spec unquote(as_fun_name)(t, :round | :exact) :: integer | Ratio.t()
     # credo:disable-for-next-line Credo.Check.Readability.Specs
-    def unquote(as_fun_name)(time) when is_time(time) do
-      Ratio.new(time, unquote(unit.duration))
+    def unquote(as_fun_name)(time, mode \\ :exact) when is_time(time) do
+      case mode do
+        :exact -> Ratio.new(time, unquote(unit.duration))
+        :round -> Ratio.new(time, unquote(unit.duration)) |> round_rational()
+      end
     end
   end)
 

test/membrane/time_test.exs

@@ -66,11 +66,11 @@ defmodule Membrane.TimeTest do
   end
 
   test "Time.to_timebase/2 works properly" do
-    assert @module.round_to_timebase(4, 2) == 2
-    assert @module.round_to_timebase(3, Ratio.new(3, 2)) == 2
-    assert @module.round_to_timebase(Ratio.new(15, 2), 2) == 4
-    assert @module.round_to_timebase(Ratio.new(15, 2), Ratio.new(3, 2)) == 5
-    assert @module.round_to_timebase(4, 10) == 0
-    assert @module.round_to_timebase(4, 7) == 1
+    assert @module.divide_by_timebase(4, 2) == 2
+    assert @module.divide_by_timebase(3, Ratio.new(3, 2)) == 2
+    assert @module.divide_by_timebase(Ratio.new(15, 2), 2) == 4
+    assert @module.divide_by_timebase(Ratio.new(15, 2), Ratio.new(3, 2)) == 5
+    assert @module.divide_by_timebase(4, 10) == 0
+    assert @module.divide_by_timebase(4, 7) == 1
   end
 end