Implement Duration and shift/2 for calendar types

lib/elixir/lib/calendar.ex

@@ -338,6 +338,34 @@ defmodule Calendar do
   @doc since: "1.15.0"
   @callback iso_days_to_end_of_day(iso_days) :: iso_days
 
+  @doc """
+  Shifts date by given duration according to its calendar.
+  """
+  @doc since: "1.17.0"
+  @callback shift_date(year, month, day, Duration.t()) :: {year, month, day}
+
+  @doc """
+  Shifts naive datetime by given duration according to its calendar.
+  """
+  @doc since: "1.17.0"
+  @callback shift_naive_datetime(
+              year,
+              month,
+              day,
+              hour,
+              minute,
+              second,
+              microsecond,
+              Duration.t()
+            ) :: {year, month, day, hour, minute, second, microsecond}
+
+  @doc """
+  Shifts time by given duration according to its calendar.
+  """
+  @doc since: "1.17.0"
+  @callback shift_time(hour, minute, second, microsecond, Duration.t()) ::
+              {hour, minute, second, microsecond}
+
   # General Helpers
 
   @doc """

lib/elixir/lib/calendar/date.ex

@@ -40,7 +40,7 @@ defmodule Date do
 
   ## Using epochs
 
-  The `add/2` and `diff/2` functions can be used for computing dates
+  The `add/2`, `diff/2` and `shift/2` functions can be used for computing dates
   or retrieving the number of days between instants. For example, if there
   is an interest in computing the number of days from the Unix epoch
   (1970-01-01):
@@ -51,6 +51,9 @@ defmodule Date do
       iex> Date.add(~D[1970-01-01], 14716)
       ~D[2010-04-17]
 
+      iex> Date.shift(~D[1970-01-01], year: 40, month: 3, week: 2, day: 2)
+      {:ok, ~D[2010-04-17]}
+
   Those functions are optimized to deal with common epochs, such
   as the Unix Epoch above or the Gregorian Epoch (0000-01-01).
   """
@@ -687,6 +690,8 @@ defmodule Date do
   The days are counted as Gregorian days. The date is returned in the same
   calendar as it was given in.
 
+  To shift a date by a `Duration`, use `Date.shift/2`.
+
   ## Examples
 
       iex> Date.add(~D[2000-01-03], -2)
@@ -757,6 +762,68 @@ defmodule Date do
     end
   end
 
+  @doc """
+  Shifts given `date` by `duration` according to its calendar.
+
+  Allowed units are: `:year, :month, :week, :day`.
+
+  When used with the default calendar `Calendar.ISO`:
+
+  Durations are collapsed before they are applied:
+  - when shifting by 1 year and 2 months the date is actually shifted by 14 months
+  - when shifting by 2 weeks and 3 days the date is shifted by 17 days
+
+  Durations are applied in order of the size of the unit: `month > day`.
+
+  Raises ArgumentError when called with time scale units.
+
+  ## Examples
+
+      iex> Date.shift(~D[2016-01-03], month: 2)
+      {:ok, ~D[2016-03-03]}
+      iex> Date.shift(~D[2016-01-30], month: 1)
+      {:ok, ~D[2016-02-29]}
+      iex> Date.shift(~D[2016-01-31], year: 4, day: 1)
+      {:ok, ~D[2020-02-01]}
+      iex> Date.shift(~D[2016-01-03], Duration.new(month: 2))
+      {:ok, ~D[2016-03-03]}
+
+  """
+  @doc since: "1.7.0"
+  @spec shift(Calendar.date(), Duration.t() | [Duration.unit()]) :: {:ok, t}
+  def shift(%{calendar: calendar} = date, %Duration{} = duration) do
+    %{year: year, month: month, day: day} = date
+    {year, month, day} = calendar.shift_date(year, month, day, duration)
+    {:ok, %Date{calendar: calendar, year: year, month: month, day: day}}
+  end
+
+  def shift(date, duration) do
+    shift(date, Duration.new(duration))
+  end
+
+  @doc """
+  Shifts given `date` by `duration` according to its calendar.
+
+  Same as `shift/2` but raises RuntimeError.
+
+  ## Examples
+
+      iex> Date.shift!(~D[2016-01-03], month: 2)
+      ~D[2016-03-03]
+
+  """
+  @doc since: "1.7.0"
+  @spec shift(Calendar.date(), Duration.t() | [Duration.unit()]) :: t
+  def shift!(date, duration) do
+    case shift(date, duration) do
+      {:ok, date} ->
+        date
+
+      reason ->
+        raise RuntimeError, "cannot shift date, reason: #{inspect(reason)}"
+    end
+  end
+
   @doc false
   def to_iso_days(%{calendar: Calendar.ISO, year: year, month: month, day: day}) do
     {Calendar.ISO.date_to_iso_days(year, month, day), {0, 86_400_000_000}}

lib/elixir/lib/calendar/datetime.ex

@@ -1610,6 +1610,7 @@ defmodule DateTime do
       iex> result.microsecond
       {21000, 3}
 
+  To shift a datetime by a `Duration`, use `DateTime.shift/3`.
   """
   @doc since: "1.8.0"
   @spec add(
@@ -1674,6 +1675,133 @@ defmodule DateTime do
     end
   end
 
+  @doc """
+  Shifts given `datetime` by `duration` according to its calendar.
+
+  Allowed units are: `:year, :month, :week, :day, :hour, :minute, :second, :microsecond`.
+
+  When it comes to time zones, this function is equivalent to shifting the wall time
+  (the time a person at said timezone would see on a clock) by the given duration.
+  Then we validate if the shifted wall time is valid. For example, in time zones that
+  observe "Daylight Saving Time", a particular wall time may not exist when moving
+  the clock forward or be ambiguous when moving the clock back.
+
+  Check `from_naive/3` for more information on the possible result types.
+
+  When used with the default calendar `Calendar.ISO`:
+
+  Durations are collapsed before they are applied:
+  - when shifting by 1 year and 2 months the date is actually shifted by 14 months
+  - weeks, days and smaller units are collapsed into seconds and microseconds
+
+  Durations are applied in order of the size of the unit: `month > day > second`.
+
+  ## Examples
+
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], month: 2)
+      {:ok, ~U[2016-03-01 00:00:00Z]}
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], year: 1, week: 4)
+      {:ok, ~U[2017-01-29 00:00:00Z]}
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], minute: 25)
+      {:ok, ~U[2016-01-01 00:25:00Z]}
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], minute: 5, microsecond: {500, 4})
+      {:ok, ~U[2016-01-01 00:05:00.0005Z]}
+  """
+  @doc since: "1.7.0"
+  @spec shift(
+          Calendar.datetime(),
+          Duration.t() | [Duration.unit()],
+          Calendar.time_zone_database()
+        ) ::
+          {:ok, t}
+          | {:ambiguous, first_datetime :: t, second_datetime :: t}
+          | {:gap, t, t}
+          | {:error,
+             :incompatible_calendars
+             | :time_zone_not_found
+             | :utc_only_time_zone_database}
+  def shift(datetime, duration, time_zone_database \\ Calendar.get_time_zone_database())
+
+  def shift(%{calendar: calendar} = datetime, %Duration{} = duration, time_zone_database) do
+    %{
+      year: year,
+      month: month,
+      day: day,
+      hour: hour,
+      minute: minute,
+      second: second,
+      microsecond: microsecond,
+      time_zone: time_zone
+    } = datetime
+
+    {year, month, day, hour, minute, second, microsecond} =
+      calendar.shift_naive_datetime(
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        second,
+        microsecond,
+        duration
+      )
+
+    from_naive(
+      %NaiveDateTime{
+        calendar: calendar,
+        year: year,
+        month: month,
+        day: day,
+        hour: hour,
+        minute: minute,
+        second: second,
+        microsecond: microsecond
+      },
+      time_zone,
+      time_zone_database
+    )
+  end
+
+  def shift(datetime, duration, time_zone_database) do
+    shift(datetime, Duration.new(duration), time_zone_database)
+  end
+
+  @doc """
+  Shifts given `datetime` by `duration` according to its calendar.
+
+  Same as `shift/2` but raises ArgumentError.
+
+  ## Examples
+
+      iex> DateTime.shift!(~U[2016-01-01 00:00:00Z], month: 2)
+      ~U[2016-03-01 00:00:00Z]
+
+  """
+  @doc since: "1.7.0"
+  @spec shift!(Calendar.datetime(), Duration.t() | [Duration.unit()]) :: t
+  def shift!(%{time_zone: time_zone} = datetime, duration) do
+    case shift(datetime, duration) do
+      {:ok, datetime} ->
+        datetime
+
+      {:ambiguous, dt1, dt2} ->
+        raise ArgumentError,
+              "cannot shift datetime #{inspect(datetime)} by #{inspect(duration)} because the result " <>
+                "is ambiguous in time zone #{time_zone} as there is an overlap " <>
+                "between #{inspect(dt1)} and #{inspect(dt2)}"
+
+      {:gap, dt1, dt2} ->
+        raise ArgumentError,
+              "cannot shift datetime #{inspect(datetime)} by #{inspect(duration)} because the result " <>
+                "does not exist in time zone #{time_zone} as there is a gap " <>
+                "between #{inspect(dt1)} and #{inspect(dt2)}"
+
+      {:error, reason} ->
+        raise ArgumentError,
+              "cannot shift datetime #{inspect(datetime)} by #{inspect(duration)}, reason: #{inspect(reason)}"
+    end
+  end
+
   @doc """
   Returns the given datetime with the microsecond field truncated to the given
   precision (`:microsecond`, `:millisecond` or `:second`).