# `Localize.Time`
[🔗](https://github.com/elixir-localize/localize/blob/v0.9.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).

# `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` is `:unicode` or `:ascii` for variant selection.
  The default is `: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*