# `Timex.Timezone`
[🔗](https://github.com/bitwalker/timex/blob/4.0.0/lib/timezone/timezone.ex#L1)

This module is used for looking up the timezone information for
a given point in time, in the desired zone. Timezones are dependent
not only on locale, but the date and time for which you are querying.
For instance, the timezone offset from UTC for `Europe/Moscow` is different
for March 3rd of 2015, than it was in 2013. These differences are important,
and as such, all functions in this module are date/time sensitive, and where
omitted, the current date/time are assumed.

In addition to lookups, this module also does conversion of datetimes from one
timezone period to another, and determining the difference between a date in one
timezone period and the same date/time in another timezone period.

# `beginning_of_day`

```elixir
@spec beginning_of_day(DateTime.t()) :: DateTime.t()
```

Shifts the provided DateTime to the beginning of the day in it's timezone

# `convert`

```elixir
@spec convert(
  date :: DateTime.t() | NaiveDateTime.t(),
  tz :: Timex.AmbiguousTimezoneInfo.t()
) ::
  DateTime.t() | Timex.AmbiguousDateTime.t() | {:error, term()}
@spec convert(
  date :: DateTime.t() | NaiveDateTime.t(),
  tz :: Timex.TimezoneInfo.t() | Timex.Types.valid_timezone()
) :: DateTime.t() | Timex.AmbiguousDateTime.t() | {:error, term()}
```

Converts a date to the given timezone, accepting a timezone name or `TimezoneInfo`.

A `NaiveDateTime` is interpreted as wall time in the destination zone. A gap in
an IANA zone or an explicit POSIX rule returns an `AmbiguousDateTime` with
`type: :gap`, whose `before` and `after` values bound the missing wall times. In an overlap,
`type: :ambiguous` contains both valid interpretations in chronological order.
Neither result chooses an interpretation for the caller. Names and
`TimezoneInfo` values follow the same rules.

A `DateTime` identifies an instant, which is preserved when changing zones.
Unknown timezone names return `{:error, :time_zone_not_found}`.

# `end_of_day`

```elixir
@spec end_of_day(DateTime.t()) :: DateTime.t()
```

Shifts the provided DateTime to the end of the day in it's timezone

# `exists?`

```elixir
@spec exists?(String.t()) :: boolean()
```

Determines if a given zone name exists

# `get`

```elixir
@spec get(Timex.Types.valid_timezone()) ::
  Timex.TimezoneInfo.t() | Timex.AmbiguousTimezoneInfo.t() | {:error, term()}
```

Gets timezone info for a given zone name and date. The date provided
can either be an Erlang datetime tuple, or a DateTime struct, and if one
is not provided, then the current instant is used. A `DateTime` is interpreted
as an instant; values without a timezone are interpreted as wall time in the
requested zone.

# `get`

```elixir
@spec get(Timex.Types.valid_timezone(), Timex.Types.valid_datetime()) ::
  Timex.TimezoneInfo.t() | Timex.AmbiguousTimezoneInfo.t() | {:error, term()}
```

# `get`

Same as `get/2`, but allows specifying whether to obtain the TimezoneInfo based
on utc time or wall time manually (`:utc` or `:wall` respectively).

# `local`

```elixir
@spec local() ::
  Timex.TimezoneInfo.t() | Timex.AmbiguousTimezoneInfo.t() | {:error, term()}
```

Gets the local timezone configuration for the current date and time.

# `local`

```elixir
@spec local(Timex.Types.valid_datetime()) ::
  Timex.TimezoneInfo.t() | Timex.AmbiguousTimezoneInfo.t() | {:error, term()}
```

Gets the local timezone configuration for the provided date and time.
A `DateTime` identifies an instant, including its UTC offset. An Erlang datetime
tuple, `NaiveDateTime`, or other value without a timezone is interpreted as local
wall time. Use `get/3` with `:local` and an explicit basis to interpret an
unzoned value as UTC instead.

# `name_of`

```elixir
@spec name_of(
  Timex.Types.valid_timezone()
  | Timex.TimezoneInfo.t()
  | Timex.AmbiguousTimezoneInfo.t()
) ::
  String.t() | {:error, :time_zone_not_found} | {:error, term()}
```

This function takes one of the varying timezone representations:

  - atoms
  - offset integers
  - shortcut names (i.e. :utc, :local, "Z", "A")

and resolves the full name of the timezone if it's able.

Canonical IANA names retain their database definitions, including the reversed
POSIX signs in `Etc/GMT` zones: `Etc/GMT-4` means UTC+04:00 and `Etc/GMT+4`
means UTC-04:00. Numeric offsets, signed offset strings, `GMT` shorthands and
synthetic `Etc/UTC` offsets use arithmetic signs instead (`GMT+4` means UTC+04:00).
Synthetic `Etc/GMT` aliases with one or two hour digits and optional `:MM`
minutes normalize to `Etc/UTC` names with the equivalent offset; for example,
`Etc/GMT-09:30` becomes `Etc/UTC+09:30`.

An unrecognized name returns `{:error, :time_zone_not_found}`.

# `resolve`

```elixir
@spec resolve(String.t(), non_neg_integer(), :utc | :wall) ::
  Timex.TimezoneInfo.t() | Timex.AmbiguousTimezoneInfo.t() | {:error, term()}
```

Given a timezone name as a string, and a date/time in the form of the number of seconds since year zero,
attempt to resolve a TimezoneInfo for that date/time. If the time is ambiguous, AmbiguousTimezoneInfo will
be returned. If no result is found, an error will be returned.

If an invalid zone name is provided, an error will be returned

# `total_offset`

# `total_offset`

# `tzdata_to_timezone`

```elixir
@spec tzdata_to_timezone(map(), String.t()) :: Timex.TimezoneInfo.t()
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*