# `Localize.Time`
[🔗](https://github.com/elixir-localize/localize/blob/v0.32.0/lib/localize/time.ex#L1)

Provides localized formatting of `Time` structs and time-like maps.

Supports both full times (`%{hour: _, minute: _, second: _}`) and
partial times (any map with one or more of `:hour`, `:minute`,
`:second`). For partial times, the format is derived from the
available fields.

Formats are defined in CLDR and described in
[TR35](http://unicode.org/reports/tr35/tr35-dates.html).

# `hour_format_from_locale`

```elixir
@spec hour_format_from_locale(Localize.LanguageTag.t() | atom() | String.t()) ::
  {:ok, :h11 | :h12 | :h23 | :h24} | {:error, Exception.t()}
```

Returns the locale's preferred hour cycle.

CLDR ships a per-territory (and per locale-territory) preference
for how time-of-day is presented. The four cycles are:

| Atom  | Range | Description                              |
| :---- | :---- | :--------------------------------------- |
| `:h11`| 0–11  | 12-hour clock, midnight is 0             |
| `:h12`| 1–12  | 12-hour clock, midnight is 12            |
| `:h23`| 0–23  | 24-hour clock, midnight is 0             |
| `:h24`| 1–24  | 24-hour clock, midnight is 24            |

A `-u-hc-` Unicode extension on the locale (e.g.
`"fr-u-hc-h12"`) overrides the territory default.

### Arguments

* `locale` is a locale name (atom or binary) or a
  `t:Localize.LanguageTag.t/0`.

### Returns

* `{:ok, hour_cycle}` where `hour_cycle` is one of `:h11`,
  `:h12`, `:h23`, `:h24`.

* `{:error, exception}` if the locale cannot be validated.

### Examples

    iex> Localize.Time.hour_format_from_locale(:ja)
    {:ok, :h23}

    iex> Localize.Time.hour_format_from_locale("en-AU")
    {:ok, :h12}

    iex> Localize.Time.hour_format_from_locale("fr-u-hc-h12")
    {:ok, :h12}

# `hour_format_from_locale!`

```elixir
@spec hour_format_from_locale!(Localize.LanguageTag.t() | atom() | String.t()) ::
  :h11 | :h12 | :h23 | :h24
```

Same as `hour_format_from_locale/1` but raises on error.

### Examples

    iex> Localize.Time.hour_format_from_locale!(:ja)
    :h23

# `to_string`

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

Formats a time according to a CLDR format pattern.

### Arguments

* `time` is a `t:Time.t/0` or any map with one or more of
  `:hour`, `:minute`, `:second` keys.

* `options` is a keyword list of options.

### Options

* `:format` is a standard format name (`:short`, `:medium`,
  `:long`, `:full`), a format skeleton atom, or a format
  pattern string. The default is `:medium` for full times.
  For partial times the format is derived from the available
  fields.

* `:locale` is a locale identifier. The default is `:en`.

* `:prefer` selects between CLDR `alt` variants. Accepts an
  atom or a list of atoms in priority order. Recognised values:
  `:unicode` / `:ascii` (NBSP and curly quotes vs ASCII) and
  `:standard` / `:variant` (a few locales publish two preferred
  forms). Examples: `prefer: :ascii`,
  `prefer: [:variant, :ascii]`. The default is
  `[:standard, :unicode]`.

### Returns

* `{:ok, formatted_string}` on success.

* `{:error, exception}` if the time cannot be formatted.

### Examples

    iex> Localize.Time.to_string(~T[14:30:00], locale: :en, prefer: :ascii)
    {:ok, "2:30:00 PM"}

    iex> Localize.Time.to_string(~T[14:30:00], format: :short, locale: :en, prefer: :ascii)
    {:ok, "2:30 PM"}

    iex> Localize.Time.to_string(%{hour: 14, minute: 30}, format: :hm, locale: :en, prefer: :ascii)
    {:ok, "2:30 PM"}

# `to_string!`

```elixir
@spec to_string!(map(), Keyword.t()) :: String.t()
```

Same as `to_string/2` but raises on error.

### Examples

    iex> Localize.Time.to_string!(~T[14:30:00], locale: :en, prefer: :ascii)
    "2:30:00 PM"

---

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