# `NervesTimeZones`
[🔗](https://github.com/nerves-time/nerves_time_zones/blob/v0.3.8/lib/nerves_time_zones.ex#L5)

Local time support for Nerves devices

The `nerves_time_zones` application provides support for local time on Nerves
devices. It does this by bundling a time zone database that's compatible with
the `zoneinfo` library and providing logic to set the local time zone with
the C runtime (and hence Erlang and Elixir).

To use, call `NervesTimeZones.set_time_zone/1` with the any IANA time zone
name (e.g., `"America/New_York"`). The time zone will be persisted so you
won't need to set it again. It is safe to always set it on boot if your
project will always be located in one time zone.

After this, calls to `NaiveDateTime.local_now/1` will return the local time.
If you would prefer `DateTime` struct, call
`DateTime.now(NervesTimeZones.get_time_zone())`.

If running a non-BEAM program that is time zone aware, you may need to set
environment variables for it to work right. See
`NervesTimeZones.tz_environment/0` for the proper settings.

# `get_time_zone`

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

Return the current local time zone

# `reset_time_zone`

```elixir
@spec reset_time_zone() :: :ok
```

Reset the time zone to the default

This cleans up any saved time zone information and reapplies the defaults.
The default time zone is "Etc/UTC", but this can be changed by adding
something like the following to your `config.exs`:

```
config :nerves_time_zones, default_time_zone: "Asia/Tokyo"
```

# `set_time_zone`

```elixir
@spec set_time_zone(String.t()) :: :ok | {:error, any()}
```

Set the local time zone

Only known time zone names can be set. Others will return an error.
`"Etc/UTC"` should always be available.

This time zone will be persisted and restored after a reboot.

# `time_zones`

```elixir
@spec time_zones() :: [String.t()]
```

Return all known time zones

This function scans the time zone database each time it's called. It's
not slow, but if you just need to verify whether a time zone exists,
call `valid_time_zone?/1` instead.

# `tz_environment`

```elixir
@spec tz_environment() :: %{required(String.t()) => String.t()}
```

Return environment variables for running OS processes

If you're using `System.cmd/3` to start an OS process that is time zone
aware, call this to set the environment appropriately. For example,
`System.cmd("my_program", [], env: NervesTimeZones.tz_environment())`

# `valid_time_zone?`

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

Return whether a time zone is valid

---

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