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

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}

@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

@spec to_parts(map(), Keyword.t()) ::
  {:ok, [%{type: atom(), value: String.t()}]} | {:error, Exception.t()}

Formats a time into typed parts, mirroring ECMA-402's formatToParts.

The parts concatenate to exactly the string to_string/2 produces with the same options. Each pattern field is tagged with its type: :hour, :minute, :second, :fractional_second, :day_period, :time_zone_name, and :literal for separators.

Arguments

• time is a Time.t/0 or any map with time keys.

• options is a keyword list of options.

Options

See to_string/2 for the supported options.

Returns

• {:ok, parts} where parts is a list of %{type: atom(), value: String.t()} maps.

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

Examples

iex> Localize.Time.to_parts(~T[14:30:05], locale: :en, format: "HH:mm")
{:ok,
 [
   %{type: :hour, value: "14"},
   %{type: :literal, value: ":"},
   %{type: :minute, value: "30"}
 ]}

@spec to_parts!(map(), Keyword.t()) :: [%{type: atom(), value: String.t()}]

Same as to_parts/2 but raises on error.

Arguments

• time is a Time.t/0 or any map with time keys.

• options is a keyword list of options. See to_parts/2.

Returns

• A list of %{type: atom(), value: String.t()} maps.

Raises

• Raises an exception if the time cannot be formatted.

Examples

iex> Localize.Time.to_parts!(~T[14:30:05], locale: :en, format: "HH:mm") |> length()
3

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

• :number_system is a CLDR numbering system name (for example, :thai). All numeric fields render in that system; a -u-nu- locale extension may be used instead. The default is the locale's number system.

• :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"}

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

Same as to_string/2 but raises on error.

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

See to_string/2 for the supported options.

Returns

• The formatted time as a string.

• Raises an exception if the time cannot be formatted.

Examples

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