Elixir v1.8.0-rc.1 Calendar.TimeZoneDatabase behaviour View Source

This module defines a behaviour for providing time zone data.

IANA provides time zone data that includes data about different UTC offsets and standard offsets for time zones.

Link to this section Summary

Types

time_zone_period()

A period where a certain combination of UTC offset, standard offset and zone abbreviation is in effect.

time_zone_period_limit()

Limit for when a certain time zone period begins or ends.

Callbacks

time_zone_period_from_utc_iso_days(arg1, arg2)

Time zone period for a point in time in UTC for a specific time zone.

time_zone_periods_from_wall_datetime(arg1, arg2)

Possible time zone periods for a certain time zone and wall clock date and time.

Link to this section Types

time_zone_period()

Specs

time_zone_period() :: %{
  optional(any()) => any(),
  :utc_offset => Calendar.utc_offset(),
  :std_offset => Calendar.std_offset(),
  :zone_abbr => Calendar.zone_abbr()
}

A period where a certain combination of UTC offset, standard offset and zone abbreviation is in effect.

For instance one period could be the summer of 2018 in "Europe/London" where summer time / daylight saving time is in effect and lasts from spring to autumn. At autumn the std_offset changes along with the zone_abbr so a different period is needed during winter.

time_zone_period_limit()

Specs

time_zone_period_limit() :: Calendar.naive_datetime()

Limit for when a certain time zone period begins or ends.

A beginning is inclusive. An ending is exclusive. Eg. if a period is from 2015-03-29 01:00:00 and until 2015-10-25 01:00:00, the period includes and begins from the begining of 2015-03-29 01:00:00 and lasts until just before 2015-10-25 01:00:00.

A beginning or end for certain periods are infinite. For instance the latest period for time zones without DST or plans to change. However for the purpose of this behaviour they are only used for gaps in wall time where the needed period limits are at a certain time.

Link to this section Callbacks

time_zone_period_from_utc_iso_days(arg1, arg2)

(since 1.8.0)

Specs

time_zone_period_from_utc_iso_days(Calendar.iso_days(), Calendar.time_zone()) ::
  {:ok, time_zone_period()}
  | {:error, :time_zone_not_found | :utc_only_time_zone_database}

Time zone period for a point in time in UTC for a specific time zone.

Takes a time zone name and a point in time for UTC and returns a time_zone_period for that point in time.

time_zone_periods_from_wall_datetime(arg1, arg2)

(since 1.8.0)

Specs

time_zone_periods_from_wall_datetime(
  Calendar.naive_datetime(),
  Calendar.time_zone()
) ::
  {:ok, time_zone_period()}
  | {:ambiguous, time_zone_period(), time_zone_period()}
  | {:gap, {time_zone_period(), time_zone_period_limit()},
     {time_zone_period(), time_zone_period_limit()}}
  | {:error, :time_zone_not_found | :utc_only_time_zone_database}

Possible time zone periods for a certain time zone and wall clock date and time.

When the provided datetime is ambiguous a tuple with :ambiguous and two possible periods. The periods in the list are sorted with the first element being the one that begins first.

When the provided datetime is in a gap - for instance during the "spring forward" when going from winter time to summer time, a tuple with :gap and two periods with limits are returned in a nested tuple. The first nested two-tuple is the period before the gap and a naive datetime with a limit for when the period ends (wall time). The second nested two-tuple is the period just after the gap and a datetime (wall time) for when the period begins just after the gap.

If there is only a single possible period for the provided datetime, the a tuple with :single and the time_zone_period is returned.