Search documentation of Localize

# Localize.Time (Localize v0.39.0)

Copy Markdown View Source

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.

## Summary

### Functions

hour_format_from_locale(locale)

Returns the locale's preferred hour cycle.

hour_format_from_locale!(locale)

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

to_string(time, options \\ [])

Formats a time according to a CLDR format pattern.

to_string!(time, options \\ [])

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

## Functions

# hour_format_from_locale(locale)

    @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 `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!(locale)

    @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(time, options \\ [])

    @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 `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!(time, options \\ [])

    @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"