Move away from rata die reference and use iso_days instead (#6328)

We chose to use the year zero in the astronomical year
numbering as a reference point, as it is also the reference
used by Calendar.ISO, the default calendar used by Elixir,

It is also the same epoch used by Erlang's :calendar module.
Note we chose to not call it gregorian epoch due to the confusion
between January 1 AC 1 and 0000-01-01. The latter actually maps
to January 1 BC 1.

We also moved away from Calendar.Julian, which could have been
based on Calendrical Calculations, and chose Calendar.Holocene,
which adds exactly 10,000 years to Calendar.ISO and as such has
a very straigh-forward implementation.

More information:

  + https://en.wikipedia.org/wiki/Year_zero
  + https://en.wikipedia.org/wiki/Holocene_calendar

Author: josevalim

lib/elixir/lib/calendar.ex

@@ -35,17 +35,16 @@ defmodule Calendar do
   @typedoc """
   The internal date format that is used when converting between calendars.
 
-  This is the amount of days including the fractional part that has passed of the last day,
-  since midnight 1 January AD 1 of the Proleptic Gregorian Calendar
-  (0000-01-01+00:00T00:00.00000 in ISO 8601 notation).
+  This is the amount of days including the fractional part that has passed of
+  the last day since 0000-01-01+00:00T00:00.00000 in ISO 8601 notation (also
+  known as midnight 1 January BC 1 of the Proleptic Gregorian Calendar).
 
   The `parts_per_day` represent how many subparts the current day is subdivided in
   (for different calendars, picking a different `parts_per_day` might make sense).
-  The `parts_in_day` represents how many of these `parts_per_day` have passed in the last day.
-
-  Thus, a Rata Die like `{1234, {1, 2}}` should be read as `1234½`.
+  The `parts_in_day` represents how many of these `parts_per_day` have passed in the
+  last day.
   """
-  @type rata_die :: {days :: integer, day_fraction}
+  @type iso_days :: {days :: integer, day_fraction}
 
   @typedoc """
   Microseconds with stored precision.
@@ -127,14 +126,14 @@ defmodule Calendar do
   @callback time_to_string(hour, minute, second, microsecond) :: String.t
 
   @doc """
-  Converts the given datetime (with time zone) into the `t:rata_die` format.
+  Converts the given datetime (with time zone) into the `t:iso_days` format.
   """
-  @callback naive_datetime_to_rata_die(year, month, day, hour, minute, second, microsecond) :: rata_die
+  @callback naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond) :: iso_days
 
   @doc """
-  Converts `t:rata_die` to the Calendar's datetime format.
+  Converts `t:iso_days` to the Calendar's datetime format.
   """
-  @callback naive_datetime_from_rata_die(rata_die) :: {year, month, day, hour, minute, second, microsecond}
+  @callback naive_datetime_from_iso_days(iso_days) :: {year, month, day, hour, minute, second, microsecond}
 
   @doc """
   Converts the given time to the `t:day_fraction` format.

lib/elixir/lib/calendar/date.ex

@@ -82,20 +82,20 @@ defmodule Date do
       366
       iex> Enum.member?(range, ~D[2001-02-01])
       true
-      iex> Enum.reduce(range, 0, fn(_date, acc) -> acc - 1 end)
+      iex> Enum.reduce(range, 0, fn _date, acc -> acc - 1 end)
       -366
   """
 
   @spec range(Calendar.date, Calendar.date) :: Date.Range.t
   def range(%{calendar: calendar} = first, %{calendar: calendar} = last) do
-    {first_days, _} = to_rata_die(first)
-    {last_days, _} = to_rata_die(last)
+    {first_days, _} = to_iso_days(first)
+    {last_days, _} = to_iso_days(last)
 
     %Date.Range{
       first: first,
       last: last,
-      first_rata_die: first_days,
-      last_rata_die: last_days,
+      first_in_iso_days: first_days,
+      last_in_iso_days: last_days,
     }
   end
 
@@ -412,7 +412,7 @@ defmodule Date do
   end
   def compare(date1, date2) do
     if Calendar.compatible_calendars?(date1.calendar, date2.calendar) do
-      case {to_rata_die(date1), to_rata_die(date2)} do
+      case {to_iso_days(date1), to_iso_days(date2)} do
         {first, second} when first > second -> :gt
         {first, second} when first < second -> :lt
         _ -> :eq
@@ -437,10 +437,12 @@ defmodule Date do
 
   ## Examples
 
-  Imagine someone implements `Calendar.Julian`:
+  Imagine someone implements `Calendar.Holocene`, a calendar based on the
+  Gregorian calendar that adds exactly 10,000 years to the current Gregorian
+  year:
 
-      iex> Date.convert(~D[2000-01-01], Calendar.Julian)
-      {:ok, %Date{calendar: Calendar.Julian, year: 1999, month: 12, day: 19}}
+      iex> Date.convert(~D[2000-01-01], Calendar.Holocene)
+      {:ok, %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}}
 
   """
   @spec convert(Calendar.date, Calendar.calendar) :: {:ok, t} | {:error, :incompatible_calendars}
@@ -451,8 +453,8 @@ defmodule Date do
     if Calendar.compatible_calendars?(calendar, target_calendar) do
       result_date =
         date
-        |> to_rata_die()
-        |> from_rata_die(target_calendar)
+        |> to_iso_days()
+        |> from_iso_days(target_calendar)
       {:ok, result_date}
     else
       {:error, :incompatible_calendars}
@@ -465,10 +467,12 @@ defmodule Date do
 
   ## Examples
 
-  Imagine someone implements `Calendar.Julian`:
+  Imagine someone implements `Calendar.Holocene`, a calendar based on the
+  Gregorian calendar that adds exactly 10,000 years to the current Gregorian
+  year:
 
-      iex> Date.convert!(~D[2000-01-01], Calendar.Julian)
-      %Date{calendar: Calendar.Julian, year: 1999, month: 12, day: 19}
+      iex> Date.convert!(~D[2000-01-01], Calendar.Holocene)
+      %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}
 
   """
   @spec convert!(Calendar.date, Calendar.calendar) :: t
@@ -500,8 +504,8 @@ defmodule Date do
   """
   @spec add(Calendar.date, integer()) :: t
   def add(%{calendar: calendar} = date, days) do
-    {rata_days, fraction} = to_rata_die(date)
-    from_rata_die({rata_days + days, fraction}, calendar)
+    {iso_days_days, fraction} = to_iso_days(date)
+    from_iso_days({iso_days_days + days, fraction}, calendar)
   end
 
   @doc """
@@ -525,33 +529,33 @@ defmodule Date do
   @spec diff(Calendar.date, Calendar.date) :: integer
   def diff(%{calendar: Calendar.ISO, year: year1, month: month1, day: day1},
            %{calendar: Calendar.ISO, year: year2, month: month2, day: day2}) do
-    Calendar.ISO.date_to_rata_die_days(year1, month1, day1) -
-      Calendar.ISO.date_to_rata_die_days(year2, month2, day2)
+    Calendar.ISO.date_to_iso_days_days(year1, month1, day1) -
+      Calendar.ISO.date_to_iso_days_days(year2, month2, day2)
   end
 
   def diff(%{calendar: calendar1} = date1, %{calendar: calendar2} = date2) do
     if Calendar.compatible_calendars?(calendar1, calendar2) do
-      {days1, _} = to_rata_die(date1)
-      {days2, _} = to_rata_die(date2)
+      {days1, _} = to_iso_days(date1)
+      {days2, _} = to_iso_days(date2)
       days1 - days2
     else
       raise ArgumentError, "cannot calculate the difference between #{inspect date1} and #{inspect date2} because their calendars are not compatible and thus the result would be ambiguous"
     end
   end
 
-  defp to_rata_die(%{calendar: Calendar.ISO, year: year, month: month, day: day}) do
-    {Calendar.ISO.date_to_rata_die_days(year, month, day), {0, 86400000000}}
+  defp to_iso_days(%{calendar: Calendar.ISO, year: year, month: month, day: day}) do
+    {Calendar.ISO.date_to_iso_days_days(year, month, day), {0, 86400000000}}
   end
-  defp to_rata_die(%{calendar: calendar, year: year, month: month, day: day}) do
-    calendar.naive_datetime_to_rata_die(year, month, day, 0, 0, 0, {0, 0})
+  defp to_iso_days(%{calendar: calendar, year: year, month: month, day: day}) do
+    calendar.naive_datetime_to_iso_days(year, month, day, 0, 0, 0, {0, 0})
   end
 
-  defp from_rata_die({days, _}, Calendar.ISO) do
-    {year, month, day} = Calendar.ISO.date_from_rata_die_days(days)
+  defp from_iso_days({days, _}, Calendar.ISO) do
+    {year, month, day} = Calendar.ISO.date_from_iso_days_days(days)
     %Date{year: year, month: month, day: day, calendar: Calendar.ISO}
   end
-  defp from_rata_die(rata_die, target_calendar) do
-    {year, month, day, _, _, _, _} = target_calendar.naive_datetime_from_rata_die(rata_die)
+  defp from_iso_days(iso_days, target_calendar) do
+    {year, month, day, _, _, _, _} = target_calendar.naive_datetime_from_iso_days(iso_days)
     %Date{year: year, month: month, day: day, calendar: target_calendar}
   end
 

lib/elixir/lib/calendar/date_range.ex

@@ -13,22 +13,21 @@ defmodule Date.Range do
   """
 
   @type t :: %__MODULE__{first: Date.t, last: Date.t,
-                         first_rata_die: rata_die_days, last_rata_die: rata_die_days}
+                         first_in_iso_days: Calendar.days,
+                         last_in_iso_days: Calendar.days}
 
-  @opaque rata_die_days :: Calendar.days
-
-  defstruct [:first, :last, :first_rata_die, :last_rata_die]
+  defstruct [:first, :last, :first_in_iso_days, :last_in_iso_days]
 
   defimpl Enumerable do
     def member?(%{first: %{calendar: calendar, year: first_year, month: first_month, day: first_day},
                   last: %{calendar: calendar, year: last_year, month: last_month, day: last_day},
-                  first_rata_die: first_rata_die, last_rata_die: last_rata_die},
+                  first_in_iso_days: first_in_iso_days, last_in_iso_days: last_in_iso_days},
                 %Date{calendar: calendar, year: year, month: month, day: day}) do
       first = {first_year, first_month, first_day}
       last = {last_year, last_month, last_day}
       date = {year, month, day}
 
-      if first_rata_die <= last_rata_die do
+      if first_in_iso_days <= last_in_iso_days do
         {:ok, date >= first and date <= last}
       else
         {:ok, date >= last and date <= first}
@@ -39,13 +38,13 @@ defmodule Date.Range do
       {:ok, false}
     end
 
-    def count(%Date.Range{first_rata_die: first_rata_die, last_rata_die: last_rata_die}) do
-      {:ok, abs(first_rata_die - last_rata_die) + 1}
+    def count(%Date.Range{first_in_iso_days: first_in_iso_days, last_in_iso_days: last_in_iso_days}) do
+      {:ok, abs(first_in_iso_days - last_in_iso_days) + 1}
     end
 
-    def reduce(%Date.Range{first_rata_die: first_rata_die, last_rata_die: last_rata_die,
+    def reduce(%Date.Range{first_in_iso_days: first_in_iso_days, last_in_iso_days: last_in_iso_days,
                            first: %{calendar: calendar}}, acc, fun) do
-      reduce(first_rata_die, last_rata_die, acc, fun, calendar, first_rata_die <= last_rata_die)
+      reduce(first_in_iso_days, last_in_iso_days, acc, fun, calendar, first_in_iso_days <= last_in_iso_days)
     end
 
     defp reduce(_x, _y, {:halt, acc}, _fun, _calendar, _up?) do
@@ -57,24 +56,24 @@ defmodule Date.Range do
     end
 
     defp reduce(x, y, {:cont, acc}, fun, calendar, up? = true) when x <= y do
-      reduce(x + 1, y, fun.(date_from_rata_days(x, calendar), acc), fun, calendar, up?)
+      reduce(x + 1, y, fun.(date_from_iso_days_days(x, calendar), acc), fun, calendar, up?)
     end
 
     defp reduce(x, y, {:cont, acc}, fun, calendar, up? = false) when x >= y do
-      reduce(x - 1, y, fun.(date_from_rata_days(x, calendar), acc), fun, calendar, up?)
+      reduce(x - 1, y, fun.(date_from_iso_days_days(x, calendar), acc), fun, calendar, up?)
     end
 
     defp reduce(_, _, {:cont, acc}, _fun, _calendar, _up) do
       {:done, acc}
     end
 
-    defp date_from_rata_days(days, Calendar.ISO) do
-      {year, month, day} = Calendar.ISO.date_from_rata_die_days(days)
+    defp date_from_iso_days_days(days, Calendar.ISO) do
+      {year, month, day} = Calendar.ISO.date_from_iso_days_days(days)
       %Date{year: year, month: month, day: day, calendar: Calendar.ISO}
     end
 
-    defp date_from_rata_days(days, calendar) do
-      {year, month, day, _, _, _, _} = calendar.naive_datetime_from_rata_die({days, {0, 86400000000}})
+    defp date_from_iso_days_days(days, calendar) do
+      {year, month, day, _, _, _, _} = calendar.naive_datetime_from_iso_days({days, {0, 86400000000}})
       %Date{year: year, month: month, day: day, calendar: calendar}
     end
   end