diff --git a/lib/plausible/timezones.ex b/lib/plausible/timezones.ex index 4ce730d97..b78f7fb43 100644 --- a/lib/plausible/timezones.ex +++ b/lib/plausible/timezones.ex @@ -7,13 +7,13 @@ defmodule Plausible.Timezones do end @doc """ - Represents a point in wall time as UTC. + Represents wall time as Etc/UTC. iex> to_utc_datetime(~N[2024-03-16 09:50:45], "Asia/Kuala_Lumpur") ~U[2024-03-16 01:50:45Z] - When the point in wall time is ambiguous - for instance during changing from summer to winter time - - the larger UTC timestamp is returned by default. + When wall time is ambiguous - for instance during changing from summer to winter time - + the larger Etc/UTC timestamp is returned by default. # before the CEST -> CET overlap iex> to_utc_datetime(~N[2018-10-28 01:59:59], "Europe/Copenhagen") @@ -37,7 +37,7 @@ defmodule Plausible.Timezones do ~U[2018-10-28 02:00:00Z] When there is a gap in wall time - for instance in spring when the clocks are turned forward - - the larger UTC timestamp (at the end of the gap) is returned by default as well. + the larger Etc/UTC timestamp (at the end of the gap) is returned by default as well. # before the CET -> CEST gap iex> to_utc_datetime(~N[2019-03-31 01:59:59], "Europe/Copenhagen") @@ -57,7 +57,7 @@ defmodule Plausible.Timezones do iex> to_utc_datetime(~N[2019-03-31 03:00:00], "Europe/Copenhagen") ~U[2019-03-31 01:00:00Z] - If the supplied time zone is invalid, the wall time is assumed to be GMT. + If the supplied time zone is invalid, the wall time is assumed to be Etc/UTC. iex> to_utc_datetime(~N[2024-03-16 09:50:45], "Europe/Asia") ~U[2024-03-16 09:50:45Z] @@ -83,14 +83,22 @@ defmodule Plausible.Timezones do defp pick_datetime(:up, _, dt), do: dt defp pick_datetime(:down, dt, _), do: dt + @doc """ + Same as `to_datetime_in_timezone/2` but extracts the date from the result. + + iex> to_date_in_timezone(~N[2024-03-16 01:50:45], "Asia/Kuala_Lumpur") + ~D[2024-03-16] + + """ @spec to_date_in_timezone(NaiveDateTime.t() | DateTime.t() | Date.t(), String.t()) :: Date.t() def to_date_in_timezone(dt, timezone) do dt |> to_datetime_in_timezone(timezone) |> DateTime.to_date() end @doc """ - Represents a point in time in a different timezone. - Naive datetimes are assumed to be in GMT timezone. + Represents a timestamp in a different timezone. + Naive datetimes are assumed to be in Etc/UTC timezone. + Dates are assumed to mean a Etc/UTC midnight. iex> to_datetime_in_timezone(~N[2024-03-16 01:50:45], "Asia/Kuala_Lumpur") #DateTime<2024-03-16 09:50:45+08:00 +08 Asia/Kuala_Lumpur> @@ -102,6 +110,9 @@ defmodule Plausible.Timezones do iex> to_datetime_in_timezone(~N[2024-03-16 01:50:45], "GMT+8") #DateTime<2024-03-16 09:50:45+08:00 +08 GMT+8> + iex> to_datetime_in_timezone(~D[2018-10-28], "Europe/Copenhagen") + #DateTime<2018-10-28 02:00:00+02:00 CEST Europe/Copenhagen> + """ @spec to_datetime_in_timezone(NaiveDateTime.t() | DateTime.t() | Date.t(), String.t()) :: DateTime.t() diff --git a/test/plausible/timezones_test.exs b/test/plausible/timezones_test.exs index f2e531cb4..4a60e8859 100644 --- a/test/plausible/timezones_test.exs +++ b/test/plausible/timezones_test.exs @@ -31,6 +31,7 @@ defmodule Plausible.TimezonesTest do end test "to_date_in_timezone/1" do + assert to_date_in_timezone(~D[2021-01-03], "Etc/UTC") == ~D[2021-01-03] assert to_date_in_timezone(~U[2015-01-13 13:00:07Z], "Etc/UTC") == ~D[2015-01-13] assert to_date_in_timezone(~N[2015-01-13 13:00:07], "Etc/UTC") == ~D[2015-01-13] assert to_date_in_timezone(~N[2015-01-13 19:00:07], "Etc/GMT+12") == ~D[2015-01-13] @@ -39,6 +40,7 @@ defmodule Plausible.TimezonesTest do end test "to_datetime_in_timezone/1" do + assert to_datetime_in_timezone(~D[2021-01-03], "Etc/UTC") == ~U[2021-01-03 00:00:00Z] assert to_datetime_in_timezone(~N[2015-01-13 13:00:07], "Etc/UTC") == ~U[2015-01-13 13:00:07Z] assert to_datetime_in_timezone(~N[2015-01-13 19:00:07], "Etc/GMT+12") == @@ -71,5 +73,29 @@ defmodule Plausible.TimezonesTest do utc_offset: 3600, std_offset: 3600 } + + ambiguous = [ + ~N[2018-10-28 00:00:00], + ~N[2018-10-28 00:30:00], + ~N[2018-10-28 01:00:00], + ~N[2018-10-28 01:30:00] + ] + + assert for(t <- ambiguous, do: inspect(to_datetime_in_timezone(t, "Europe/Copenhagen"))) == [ + "#DateTime<2018-10-28 02:00:00+02:00 CEST Europe/Copenhagen>", + "#DateTime<2018-10-28 02:30:00+02:00 CEST Europe/Copenhagen>", + "#DateTime<2018-10-28 02:00:00+01:00 CET Europe/Copenhagen>", + "#DateTime<2018-10-28 02:30:00+01:00 CET Europe/Copenhagen>" + ] + + gap = [ + ~N[2019-03-31 00:59:59], + ~N[2019-03-31 01:00:00] + ] + + assert for(t <- gap, do: inspect(to_datetime_in_timezone(t, "Europe/Copenhagen"))) == [ + "#DateTime<2019-03-31 01:59:59+01:00 CET Europe/Copenhagen>", + "#DateTime<2019-03-31 03:00:00+02:00 CEST Europe/Copenhagen>" + ] end end