Localize.Time (Localize v0.32.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:

AtomRangeDescription
:h110–1112-hour clock, midnight is 0
:h121–1212-hour clock, midnight is 12
:h230–2324-hour clock, midnight is 0
:h241–2424-hour clock, midnight is 24

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

Arguments

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"