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)
+      ~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,49 @@ defmodule Date do
     end
   end
 
+  @doc """
+  Shifts given `date` by `duration` according to its calendar.
+
+  Allowed units are: `:year`, `:month`, `:week`, `:day`.
+
+  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 an `ArgumentError` when called with time scale units.
+
+  ## Examples
+
+      iex> Date.shift(~D[2016-01-03], month: 2)
+      ~D[2016-03-03]
+      iex> Date.shift(~D[2016-01-30], month: 1)
+      ~D[2016-02-29]
+      iex> Date.shift(~D[2016-01-31], year: 4, day: 1)
+      ~D[2020-02-01]
+      iex> Date.shift(~D[2016-01-03], Duration.new(month: 2))
+      ~D[2016-03-03]
+
+      # leap years
+      iex> Date.shift(~D[2024-02-29], year: 1)
+      ~D[2025-02-28]
+      iex> Date.shift(~D[2024-02-29], year: 4)
+      ~D[2028-02-29]
+
+  """
+  @doc since: "1.17.0"
+  @spec shift(Calendar.date(), Duration.t() | [Duration.unit()]) :: 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)
+    %Date{calendar: calendar, year: year, month: month, day: day}
+  end
+
+  def shift(date, duration) do
+    shift(date, Duration.new(duration))
+  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,143 @@ 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`.
+
+  Shifting datetimes in time zones that observe "Daylight Saving Time" across
+  summer/winter time will add/remove one hour from the resulting datetime.
+  This ensures `shift/3` always returns a valid datetime.
+
+      dt = DateTime.new!(~D[2019-03-31], ~T[01:00:00], "Europe/Copenhagen")
+      DateTime.shift(dt, hour: 1)
+      #=> #DateTime<2019-03-31 03:00:00+02:00 CEST Europe/Copenhagen>
+
+      dt = DateTime.new!(~D[2018-11-04], ~T[00:00:00], "America/Los_Angeles")
+      DateTime.shift(dt, hour: 2)
+      #=> #DateTime<2018-11-04 01:00:00-08:00 PST America/Los_Angeles>
+
+  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 > second > microsecond`.
+
+  ## Examples
+
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], month: 2)
+      ~U[2016-03-01 00:00:00Z]
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], year: 1, week: 4)
+      ~U[2017-01-29 00:00:00Z]
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], minute: 25)
+      ~U[2016-01-01 00:25:00Z]
+      iex> DateTime.shift(~U[2016-01-01 00:00:00Z], minute: 5, microsecond: {500, 4})
+      ~U[2016-01-01 00:05:00.0005Z]
+
+      # leap years
+      iex> DateTime.shift(~U[2024-02-29 00:00:00Z], year: 1)
+      ~U[2025-02-28 00:00:00Z]
+      iex> DateTime.shift(~U[2024-02-29 00:00:00Z], year: 4)
+      ~U[2028-02-29 00:00:00Z]
+
+  """
+  @doc since: "1.17.0"
+  @spec shift(
+          Calendar.datetime(),
+          Duration.t() | [Duration.unit()],
+          Calendar.time_zone_database()
+        ) :: t
+  def shift(datetime, duration, time_zone_database \\ Calendar.get_time_zone_database())
+
+  def shift(
+        %{calendar: calendar, time_zone: "Etc/UTC"} = datetime,
+        %Duration{} = duration,
+        _time_zone_database
+      ) do
+    %{
+      year: year,
+      month: month,
+      day: day,
+      hour: hour,
+      minute: minute,
+      second: second,
+      microsecond: microsecond
+    } = datetime
+
+    {year, month, day, hour, minute, second, microsecond} =
+      calendar.shift_naive_datetime(
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        second,
+        microsecond,
+        duration
+      )
+
+    %DateTime{
+      year: year,
+      month: month,
+      day: day,
+      hour: hour,
+      minute: minute,
+      second: second,
+      microsecond: microsecond,
+      time_zone: "Etc/UTC",
+      zone_abbr: "UTC",
+      std_offset: 0,
+      utc_offset: 0
+    }
+  end
+
+  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,
+      std_offset: std_offset,
+      utc_offset: utc_offset,
+      time_zone: time_zone
+    } = datetime
+
+    {year, month, day, hour, minute, second, {_, precision} = microsecond} =
+      calendar.shift_naive_datetime(
+        year,
+        month,
+        day,
+        hour,
+        minute,
+        second,
+        microsecond,
+        duration
+      )
+
+    result =
+      calendar.naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond)
+      |> apply_tz_offset(utc_offset + std_offset)
+      |> shift_zone_for_iso_days_utc(calendar, precision, time_zone, time_zone_database)
+
+    case result do
+      {:ok, result_datetime} ->
+        result_datetime
+
+      {:error, error} ->
+        raise ArgumentError,
+              "cannot shift #{inspect(datetime)} to #{inspect(duration)} (with time zone " <>
+                "database #{inspect(time_zone_database)}), reason: #{inspect(error)}"
+    end
+  end
+
+  def shift(datetime, duration, time_zone_database) do
+    shift(datetime, Duration.new(duration), time_zone_database)
+  end
+
   @doc """
   Returns the given datetime with the microsecond field truncated to the given
   precision (`:microsecond`, `:millisecond` or `:second`).