Kalends.AmbiguousDateTime
AmbiguousDateTime provides a struct which represents an ambiguous time and date in a certain time zone. These structs will be returned from the DateTime.from_erl/2 function when the provided time is ambiguous.
AmbiguousDateTime contains two DateTime structs. For instance they can represent both a DST and non-DST time. If clocks are turned back an hour at 2:00 when going from summer to winter time then the "wall time" between 1:00 and 2:00 happens twice. One of them is on DST and one of them is not.
The provided functions can be used to choose one of the two DateTime structs.
Summary↑
| disamb(ambiguous_date_time, filtering_func) | Disambiguate an AmbiguousDateTime according to filtering function provided as the second parameter |
| disamb_total_off(ambiguous_date_time, total_off_secs) | Disambiguate an AmbiguousDateTime by total offset. Total offset would be UTC offset plus standard offset |
Functions
Disambiguate an AmbiguousDateTime according to filtering function provided as the second parameter
Examples
We provide a function that returns true if the abbreviation is "UYT"
iex> {:ambiguous, am} = Kalends.DateTime.from_erl({{2014, 3, 9}, {1, 1, 1}}, "America/Montevideo"); am |> Kalends.AmbiguousDateTime.disamb(fn(dt) -> dt.abbr == "UYT" end)
{:ok, %Kalends.DateTime{abbr: "UYT", day: 9, hour: 1, min: 1, month: 3, sec: 1, std_off: 0, timezone: "America/Montevideo", utc_off: -10800, year: 2014}}A function that always returns false
iex> {:ambiguous, am} = Kalends.DateTime.from_erl({{2014, 3, 9}, {1, 1, 1}}, "America/Montevideo"); am |> Kalends.AmbiguousDateTime.disamb(fn(_dt) -> false end)
{:error, :no_matches}A function that always returns true
iex> {:ambiguous, am} = Kalends.DateTime.from_erl({{2014, 3, 9}, {1, 1, 1}}, "America/Montevideo"); am |> Kalends.AmbiguousDateTime.disamb(fn(_dt) -> true end)
{:error, :more_than_one_match}Disambiguate an AmbiguousDateTime by total offset. Total offset would be UTC offset plus standard offset.
If only one of the possible data times contained in the ambiguous_date_time matches the offset a tuple with :ok and the matching DateTime is returned.
Total offset
For instance, at the time of this writing, for Berlin there is a 1 hour UTC offset. In the summer, there is another hour of standard offset. This means that in the summer the total offset is 2 hours or 7200 seconds.
Examples
iex> {:ambiguous, am} = Kalends.DateTime.from_erl({{2014, 3, 9}, {1, 1, 1}}, "America/Montevideo"); am |> Kalends.AmbiguousDateTime.disamb_total_off(-10800)
{:ok, %Kalends.DateTime{abbr: "UYT", day: 9, hour: 1, min: 1, month: 3, sec: 1, std_off: 0, timezone: "America/Montevideo", utc_off: -10800, year: 2014}}
iex> {:ambiguous, am} = Kalends.DateTime.from_erl({{2014, 3, 9}, {1, 1, 1}}, "America/Montevideo"); am |> Kalends.AmbiguousDateTime.disamb_total_off(0)
{:error, :no_matches}