# `Localize.Ecto.Type.TimeZone`
[🔗](https://github.com/elixir-localize/localize_sql/blob/v1.0.1/lib/localize/ecto/type/time_zone.ex#L1)

An `Ecto.Type` for IANA time zone identifiers, validated against the CLDR zone inventory.

Casting accepts a canonical IANA name ("Australia/Sydney"), any CLDR-known alias ("Australia/NSW"), or a BCP 47 short zone identifier as used by the `-u-tz-` locale keyword ("ausyd"); all of them cast to the canonical IANA name, so the stored value is always canonical. Unknown names fail the cast with a validation message.

    schema "events" do
      field :time_zone, Localize.Ecto.Type.TimeZone
    end

The canonicalization is also available directly via `canonicalize/1` and `canonicalize!/1` — the latter is used by the `Localize.Ecto.at_time_zone/2` query helper to reject unknown zones before they reach the server.

# `canonicalize`

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

Canonicalizes a time zone identifier to its canonical IANA name.

### Arguments

* `zone` is a canonical IANA name, a CLDR-known alias, or a BCP 47 short zone identifier.

### Returns

* `{:ok, canonical_name}`, or

* `{:error, exception}` when the zone is unknown.

### Examples

    iex> Localize.Ecto.Type.TimeZone.canonicalize("Australia/Sydney")
    {:ok, "Australia/Sydney"}

    iex> Localize.Ecto.Type.TimeZone.canonicalize("Australia/NSW")
    {:ok, "Australia/Sydney"}

    iex> Localize.Ecto.Type.TimeZone.canonicalize("ausyd")
    {:ok, "Australia/Sydney"}

    iex> {:error, %Localize.UnknownTimezoneError{}} = Localize.Ecto.Type.TimeZone.canonicalize("Mars/Olympus_Mons")

# `canonicalize!`

```elixir
@spec canonicalize!(String.t()) :: String.t()
```

Canonicalizes a time zone identifier or raises.

### Arguments

* `zone` is a canonical IANA name, a CLDR-known alias, or a BCP 47 short zone identifier.

### Returns

* The canonical IANA name string.

### Examples

    iex> Localize.Ecto.Type.TimeZone.canonicalize!("Australia/NSW")
    "Australia/Sydney"

# `embed_as`

# `equal?`

---

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