# `TimeZoneInfo`
[🔗](https://github.com/hrzndhrn/time_zone_info/blob/main/lib/time_zone_info.ex#L1)

`TimeZoneInfo` provides a time zone database for
[Elixir](https://elixir-lang.org/) using the data from the
[the Internet Assigned Numbers Authority (IANA)](https://www.iana.org/time-zones).

Therefore `TimeZoneInfo` contains an implementation of the
`Calendar.TimeZoneDatabase` behaviour under `TimeZoneInfo.TimeZoneDatabase`.

# `data`

```elixir
@type data() :: %{
  version: String.t(),
  time_zones: %{required(Calendar.time_zone()) => [transition()]},
  rules: %{required(rule_name()) => [rule()]},
  links: %{required(Calendar.time_zone()) => Calendar.time_zone()},
  config: data_config()
}
```

The data structure containing all informations for `TimeZoneInfo`.

# `data_config`

```elixir
@type data_config() :: [
  files: [String.t()],
  time_zones: time_zones(),
  lookahead: non_neg_integer()
]
```

The configuration for data generation.

- `:files`: The list of files from the IANA DB download.
- `:time_zones`: The list of time zones that will be used. The atom `:all`
  indicates that all time zones from the IANA DB will be used.
- `:lookahead`: Number of years for which data are precalculated.

See `Config` page for more information.

# `gregorian_seconds`

```elixir
@type gregorian_seconds() :: integer()
```

Seconds since year 0 in the gregorian calendar.

# `rule`

```elixir
@type rule() ::
  {{Calendar.month(), TimeZoneInfo.IanaParser.day(),
    {Calendar.hour(), Calendar.minute(), Calendar.second()}}, time_standard(),
   Calendar.std_offset(), TimeZoneInfo.Transformer.Abbr.letters()}
```

A rule representation.

# `rule_name`

```elixir
@type rule_name() :: String.t()
```

The name of a rule set that can be found in the IANA data.

# `rules_ref`

```elixir
@type rules_ref() ::
  {Calendar.utc_offset(), rule_name(), TimeZoneInfo.Transformer.Abbr.format()}
```

A reference to a rule set. The reference also contains `utc_offset` and
`format`,
The reference contains `utc_offset` and `format` because these values are needed
to apply a `rule`.

# `time_standard`

```elixir
@type time_standard() :: :wall | :standard | :gmt | :utc | :zulu
```

The time standards used by IANA.

# `time_zone_period`

```elixir
@type time_zone_period() ::
  {Calendar.utc_offset(), Calendar.std_offset(), Calendar.zone_abbr(),
   wall_period()}
```

A period where a certain combination of UTC offset, standard offset and zone
abbreviation is in effect. The `wall_period` contains the start and end of the
time zone period in wall time.

# `time_zones`

```elixir
@type time_zones() :: :all | [Calendar.time_zone()]
```

# `transition`

```elixir
@type transition() :: {gregorian_seconds() | NaiveDateTime.t(), zone_state()}
```

A transition marks a point in time when one or more of the values `utc-offset`,
`std_offset` or `zone-abbr` change.

# `wall_period`

```elixir
@type wall_period() :: {NaiveDateTime.t(), NaiveDateTime.t()}
```

The wall time period represented in a tuple with two naive date times.

# `zone_state`

```elixir
@type zone_state() :: time_zone_period() | rules_ref()
```

The `zone_state` is either a `timezone_period` or a `rules_ref`.

# `data`

```elixir
@spec data(binary(), data_config()) ::
  {:ok, binary() | data(), String.t()} | {:error, term()}
```

Generates `TimeZoneInfo.data` from the given `iana_data_archive`.

# `iana_version`

```elixir
@spec iana_version() :: String.t()
```

Returns the version of the IANA database.

# `info`

```elixir
@spec info() :: map()
```

Returns infos about persisted and stored data.

# `next_update`

```elixir
@spec next_update() :: DateTime.t() | :never | :error
```

Returns the date time in UTC for the next update. Retruns `:never` if the
automated update disabled.

# `state`

```elixir
@spec state() :: :ok | {:next, non_neg_integer()} | {:error, term()}
```

Returns the state of `TimeZoneInfo`.

Returns
- `:ok` if everything runs normal and the automated update is disabled.
- `{:next, seconds}` if everything runs normal.
- `{:error, reason}` in case of an error.

# `time_zones`

```elixir
@spec time_zones([{:links, :ignore | :only | :include}]) :: [Calendar.time_zone()]
```

Returns the list of all available time zones with or without links. The option
`:links` can be used to customize the list.

Values for `:links`:
- `:ignore` just the time zone names will be returned
- `:only` just the link names will be returned
- `:include` the time zone and link names will be returned (default)

The list will be sorted.

# `update`

```elixir
@spec update(opt :: :run | :force) ::
  :ok | {:next, non_neg_integer()} | {:error, term()}
```

Triggers the update process. Withe the `opt` `:force` the update will be
forced.

---

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