@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 parse(String.t(), Keyword.t()) :: {:ok, Time.t()} | {:error, Exception.t()}

Parses a localized time string.

Parsing lives in the companion calendrical package, which carries the calendar systems Localize formats for. calendrical depends on Localize, so Localize resolves it at runtime rather than depending on it in return — add {:calendrical, "~> 1.0"} to your dependencies to use this function.

Arguments

• string is a string in any shape the locale accepts, including the locale's CLDR short, medium, long and full patterns and ISO 8601.

• options is a keyword list of options.

Options

• :locale is a locale identifier. The default is the locale returned by Localize.get_locale/0.

• Remaining options are passed to Calendrical.Time.parse/2, which documents them.

Returns

• {:ok, value} where value is a t:Time.t() , or

• {:error, exception} if the string does not parse, or a Localize.DependencyRequiredError.t/0 if calendrical is not among the application's dependencies.

Examples

Shown rather than run as doctests: calendrical is not a dependency of Localize itself, so the call does not resolve in this package's own tests.

Localize.Time.parse("14:30", locale: :de)
#=> {:ok, ~T[14:30:00]}

Localize.Time.parse("2:30 PM", locale: :en)
#=> {:ok, ~T[14:30:00]}

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