Timex.TimezoneInfo (timex v3.7.13)

All relevant timezone information for a given period, i.e. Europe/Moscow on March 3rd, 2013

Notes:

full_name is the name of the zone, but does not indicate anything about the current period (i.e. CST vs CDT)
abbreviation is the abbreviated name for the zone in the current period, i.e. "America/Chicago" on 3/30/15 is "CDT"
offset_std is the offset in seconds from standard time for this period
offset_utc is the offset in seconds from UTC for this period

Spec:

day_of_week: :sunday, :monday, :tuesday, etc
datetime: {{year, month, day}, {hour, minute, second}}
from: :min | {day_of_week, datetime}, when this zone starts
until: :max | {day_of_week, datetime}, when this zone ends

Summary

Types

datetime()

day_of_week()

from_constraint()

offset()

t()

until_constraint()

Functions

create(name, abbr, offset_utc, offset_std, from, until)

Create a custom timezone if a built-in one does not meet your needs.

format_offset(tzinfo)

Formats the offset of a Timex.TimezoneInfo struct.

from_datetime(date_time)

Types

datetime()

@type datetime() :: {{non_neg_integer(), 1..12, 1..31}, {0..24, 0..59, 0..60}}

day_of_week()

@type day_of_week() ::
  :sunday | :monday | :tuesday | :wednesday | :thursday | :friday | :saturday

from_constraint()

@type from_constraint() :: :min | {day_of_week(), datetime()}

offset()

@type offset() :: -85399..85399

t()

@type t() :: %Timex.TimezoneInfo{
  abbreviation: String.t(),
  from: from_constraint(),
  full_name: String.t(),
  offset_std: offset(),
  offset_utc: offset(),
  until: until_constraint()
}

until_constraint()

@type until_constraint() :: :max | {day_of_week(), datetime()}

Functions

create(name, abbr, offset_utc, offset_std, from, until)

@spec create(
  String.t(),
  String.t(),
  offset(),
  offset(),
  from_constraint(),
  until_constraint()
) ::
  t() | {:error, String.t()}

Create a custom timezone if a built-in one does not meet your needs.

You must provide the name, abbreviation, offset from UTC, daylight savings time offset, and the from/until reference points for when the zone takes effect and ends.

To clarify the two offsets, offset_utc is the absolute offset relative to UTC, offset_std is the offset to apply to offset_utc which gives us the offset from UTC during daylight savings time for this timezone. If DST does not apply for this zone, simply set it to 0.

The from/until reference points must meet the following criteria:

Be set to :min for from, or :max for until, which represents "infinity" for the start/end of the zone period
OR, be a tuple of {day_of_week, datetime}, where:
- day_of_week is an atom like :sunday
- datetime is an Erlang datetime tuple, e.g. {{2016,10,8},{2,0,0}}

IMPORTANT: Offsets are in seconds, not minutes. If you do not ensure they are in the correct unit, runtime errors or incorrect results are probable.

Examples

iex> Elixir.Timex.TimezoneInfo.create("Etc/Test", "TST", 120*60, 0, :min, :max)
%TimezoneInfo{full_name: "Etc/Test", abbreviation: "TST", offset_std: 7200, offset_utc: 0, from: :min, until: :max}
...> Elixir.Timex.TimezoneInfo.create("Etc/Test", "TST", 24*60*60, 0, :min, :max)
{:error, "invalid timezone offset '86400'"}

format_offset(tzinfo)

@spec format_offset(tzinfo :: t()) :: String.t()

Formats the offset of a Timex.TimezoneInfo struct.

Examples

iex> tzinfo = Timex.Timezone.get("Etc/Greenwich", ~U[2022-01-01 00:00:00Z])
...> Elixir.Timex.TimezoneInfo.format_offset(tzinfo)
"+00:00:00"

iex> tzinfo = Timex.Timezone.get("Africa/Nairobi", ~U[2022-01-01 00:00:00Z])
...> Elixir.Timex.TimezoneInfo.format_offset(tzinfo)
"+03:00:00"

iex> tzinfo = Timex.Timezone.get("America/New_York", ~U[2022-01-01 00:00:00Z])
...> Elixir.Timex.TimezoneInfo.format_offset(tzinfo)
"-05:00:00"