Update Membrane.Time API (#494)

* Remove or rename Membrane.Time.round_to_* functions

CHANGELOG.md

@@ -5,14 +5,15 @@
   * Add children groups - a mechanism that allows refering to multiple children with a single identifier. 
   * Rename `remove_child_t` action into `remove_children_t` and allow for removing a children group with a single action.
   * Add an ability to spawn anonymous children.
+  * Replace `Membrane.Time.round_to_<unit_name>` with `Membrane.Time.as_<unit_name>/2` with second argument equal `:round`. Rename `Membrane.Time.round_to_timebase` 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)
  * Add `handle_call/3` callback in the pipeline, as well as a `:reply` and `:reply_to` actions. Rename `handle_other/3` callback into `handle_info/3` [#334](https://github.com/membraneframework/membrane_core/issues/334)
  * Add `Membrane.FilterAggregator` that allows to run multiple filters sequentially within one process. [#355](https://github.com/membraneframework/membrane_core/pull/355)
  * Log info about element's playback state change as debug, not as debug_verbose. [#430](https://github.com/membraneframework/membrane_core/pull/430)
- * Rename `Membrane.Time.to_<unit name>/1` into `Membrane.Time.round_to_<unit name>/1` to indicate that the result will be rounded. Make `Membrane.Time.<plural unit name>/1` accept `%Ratio{}` as an argument. Add `Membrane.Time.round_to_timebase/2` function.
+ * Rename `Membrane.Time.to_<unit name>/1` into `Membrane.Time.round_to_<unit name>/1` to indicate that the result will be rounded. Make `Membrane.Time.<plural unit name>/1` accept `%Ratio{}` as an argument. Add `Membrane.Time.round_to_timebase` function.
  * New `spec` action syntax - the structure of pipeline is now defined with the use of `Membrane.ChildrenSpec`
  * Rename `:caps` to `:stream_format`.
  * Use Elixir patterns as `:accepted_format` in pad definition.

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 a timebase. The result is 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,22 @@ 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 the `mode` argument is set to `:exact` (default), the result is
+    represented as a rational number. Otherwise, if the `mode` is
+    `:round`, the result is rounded to the nearest integer.
     """
-    @spec unquote(as_fun_name)(t) :: integer | Ratio.t()
+    @spec unquote(as_fun_name)(t, mode :: :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