tzdata v1.0.3 Tzdata View Source

The Tzdata module provides data from the IANA tz database. Also known as the Olson/Eggert database, zoneinfo, tzdata and other names.

A list of time zone names (e.g. America/Los_Angeles) are provided. As well as functions for finding out the UTC offset, abbreviation, standard offset (DST) for a specific point in time in a certain timezone.

Link to this section Summary

Functions

Takes the name of a zone. Returns true if zone exists and is canonical. Otherwise false.

Like zone_list, but excludes aliases for zones.

The time when the leap second information returned from the other leap second related function expires. The date-time is in UTC.

Get a list of known leap seconds. The leap seconds are datetime tuples representing the extra leap second to be inserted. The date-times are in UTC.

Get a list of maps with known leap seconds and the difference between UTC and the TAI in seconds.

Returns a map of links. Also known as aliases.

Returns a list of periods for the zone_name provided as an argument.

Get the periods that cover a certain point in time. Usually it will be a list with just one period. But in some cases it will be zero or two periods. For instance when going from summer to winter time (DST to standard time) there will be an overlap if time_type is :wall.

Returns tzdata release version as a string.

Takes the name of a zone. Returns true if zone exists and is an alias. Otherwise false.

A list of aliases for zone names. For instance Europe/Jersey is an alias for Europe/London. Aliases are also known as linked zones.

Takes the name of a zone. Returns true if zone exists. Otherwise false.

zone_list provides a list of all the zone names that can be used with DateTime. This includes aliases.

Returns a map with keys being group names and the values lists of time zone names. The group names mirror the file names used by the tzinfo database.

Link to this section Types

Link to this type

gregorian_seconds()

View Source
gregorian_seconds() :: non_neg_integer()
Link to this type

time_zone_period()

View Source
time_zone_period() :: %{
  from: %{
    standard: time_zone_period_limit(),
    utc: time_zone_period_limit(),
    wall: time_zone_period_limit()
  },
  std_off: integer(),
  until: %{
    standard: time_zone_period_limit(),
    utc: time_zone_period_limit(),
    wall: time_zone_period_limit()
  },
  utc_off: integer(),
  zone_abbr: String.t()
}
Link to this type

time_zone_period_limit()

View Source
time_zone_period_limit() :: gregorian_seconds() | :min | :max

Link to this section Functions

Link to this function

canonical_zone?(name)

View Source
canonical_zone?(Calendar.time_zone()) :: boolean()

Takes the name of a zone. Returns true if zone exists and is canonical. Otherwise false.

iex> Tzdata.canonical_zone? "Europe/London"
true
iex> Tzdata.canonical_zone? "Europe/Jersey"
false
Link to this function

canonical_zone_list()

View Source
canonical_zone_list() :: [Calendar.time_zone()]
canonical_zone_list() :: [Calendar.time_zone()]

Like zone_list, but excludes aliases for zones.

Link to this function

leap_second_data_valid_until()

View Source
leap_second_data_valid_until() :: :calendar.datetime()

The time when the leap second information returned from the other leap second related function expires. The date-time is in UTC.

Example

Tzdata.leap_second_data_valid_until
{{2015, 12, 28}, {0, 0, 0}}
Link to this function

leap_seconds()

View Source
leap_seconds() :: [:calendar.datetime()]

Get a list of known leap seconds. The leap seconds are datetime tuples representing the extra leap second to be inserted. The date-times are in UTC.

See also leap_seconds_with_tai_diff/1

Example

iex> Tzdata.leap_seconds |> Enum.take(2)
[{{1972,  6, 30}, {23, 59, 60}},
 {{1972, 12, 31}, {23, 59, 60}}]
Link to this function

leap_seconds_with_tai_diff()

View Source
leap_seconds_with_tai_diff() :: [
  %{date_time: :calendar.datetime(), tai_diff: integer()}
]

Get a list of maps with known leap seconds and the difference between UTC and the TAI in seconds.

See also leap_seconds/1

Example

iex> Tzdata.leap_seconds_with_tai_diff |> Enum.take(2)
[%{date_time: {{1972,  6, 30}, {23, 59, 60}}, tai_diff: 11},
 %{date_time: {{1972, 12, 31}, {23, 59, 60}}, tai_diff: 12}]

Returns a map of links. Also known as aliases.

iex> Tzdata.links["Europe/Jersey"]
"Europe/London"
Link to this function

periods(zone_name)

View Source
periods(Calendar.time_zone()) :: {:ok, [time_zone_period()]} | {:error, atom()}

Returns a list of periods for the zone_name provided as an argument.

A period in this case is a period of time where the UTC offset and standard offset are in a certain way. When they change, for instance in spring when DST takes effect, a new period starts. For instance a period can begin in spring when winter time ends and summer time begins. The period lasts until DST ends.

If either the UTC or standard offset change for any reason, a new period begins. For instance instead of DST ending or beginning, a rule change that changes the UTC offset will also mean a new period.

The result is tagged with :ok if the zone_name is correct.

The from and until times can be :mix, :max or gregorian seconds.

Example

iex> Tzdata.periods("Europe/Madrid") |> elem(1) |> Enum.take(1)
[%{from: %{standard: :min, utc: :min, wall: :min}, std_off: 0,
  until: %{standard: 59989763760, utc: 59989764644, wall: 59989763760},
  utc_off: -884, zone_abbr: "LMT"}]
iex> Tzdata.periods("Not existing")
{:error, :not_found}
Link to this function

periods_for_time(zone_name, time_point, time_type)

View Source
periods_for_time(
  Calendar.time_zone(),
  gregorian_seconds(),
  :standard | :wall | :utc
) :: [time_zone_period()] | {:error, term()}

Get the periods that cover a certain point in time. Usually it will be a list with just one period. But in some cases it will be zero or two periods. For instance when going from summer to winter time (DST to standard time) there will be an overlap if time_type is :wall.

zone_name should be a valid time zone name. The function zone_list/0 provides a valid list of valid zone names.

time_point is the point in time in gregorian seconds (see erlang calendar module documentation for more info on gregorian seconds).

Valid values for time_type is :utc, :wall or :standard.

Examples

# 63555753600 seconds is equivalent to {{2015, 1, 1}, {0, 0, 0}}
iex> Tzdata.periods_for_time("Asia/Tokyo", 63587289600, :wall)
[%{from: %{standard: 61589289600, utc: 61589257200, wall: 61589289600}, std_off: 0,
  until: %{standard: :max, utc: :max, wall: :max}, utc_off: 32400, zone_abbr: "JST"}]

# 63612960000 seconds is equivalent to 2015-10-25 02:40:00 and is an ambiguous
# wall time for the zone. So two possible periods will be returned.
iex> Tzdata.periods_for_time("Europe/Copenhagen", 63612960000, :wall)
[%{from: %{standard: 63594813600, utc: 63594810000, wall: 63594817200}, std_off: 3600,
        until: %{standard: 63612957600, utc: 63612954000, wall: 63612961200}, utc_off: 3600, zone_abbr: "CEST"},
      %{from: %{standard: 63612957600, utc: 63612954000, wall: 63612957600}, std_off: 0,
        until: %{standard: 63626263200, utc: 63626259600, wall: 63626263200}, utc_off: 3600, zone_abbr: "CET"}]

# 63594816000 seconds is equivalent to 2015-03-29 02:40:00 and is a
# non-existing wall time for the zone. It is spring and the clock skips that hour.
iex> Tzdata.periods_for_time("Europe/Copenhagen", 63594816000, :wall)
[]
Link to this function

tzdata_version()

View Source
tzdata_version() :: String.t()

Returns tzdata release version as a string.

Example:

Tzdata.tzdata_version
"2014i"

Takes the name of a zone. Returns true if zone exists and is an alias. Otherwise false.

iex> Tzdata.zone_alias? "Europe/Jersey"
true
iex> Tzdata.zone_alias? "Europe/London"
false

A list of aliases for zone names. For instance Europe/Jersey is an alias for Europe/London. Aliases are also known as linked zones.

Link to this function

zone_exists?(name)

View Source
zone_exists?(String.t()) :: boolean()

Takes the name of a zone. Returns true if zone exists. Otherwise false.

iex> Tzdata.zone_exists? "Pacific/Auckland"
true
iex> Tzdata.zone_exists? "America/Sao_Paulo"
true
iex> Tzdata.zone_exists? "Europe/Jersey"
true

zone_list provides a list of all the zone names that can be used with DateTime. This includes aliases.

Link to this function

zone_lists_grouped()

View Source
zone_lists_grouped() :: %{required(atom()) => [Calendar.time_zone()]}

Returns a map with keys being group names and the values lists of time zone names. The group names mirror the file names used by the tzinfo database.