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 a partial time a standard format, or no format, derives
the skeleton from the fields present, with the hour in the locale's hour
cycle; a skeleton or pattern that asks for a field the time does not
have returns Localize.DateTimeInvalidInputError.
Formats are defined in CLDR and described in TR35.
Summary
Functions
Returns the locale's preferred hour cycle.
Same as hour_format_from_locale/1 but raises on error.
Parses a localized time string.
Parses a time written with a Calendar.strftime/3 format.
Formats a time into typed parts, mirroring ECMA-402's formatToParts.
Same as to_parts/2 but raises on error.
Formats a time according to a CLDR format pattern.
Same as to_string/2 but raises on error.
Functions
@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. CLDR 49's
technical-preview c12 and c24 ask for the locale's own 12-hour
or 24-hour cycle, which TR35 resolves from the cycles the region
allows: c12 is :h11 where K is allowed before h, as in
Japan, and :h12 otherwise.
Arguments
localeis a locale name (atom or binary) or aLocalize.LanguageTag.t/0.
Returns
{:ok, hour_cycle}wherehour_cycleis 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}
iex> Localize.Time.hour_format_from_locale("ja-u-hc-c12")
{:ok, :h11}
iex> Localize.Time.hour_format_from_locale("en-US-u-hc-c24")
{:ok, :h23}
@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.
Arguments
localeis a locale identifier or aLocalize.LanguageTag.t/0.
Returns
:h11,:h12,:h23or:h24.
Raises the exception hour_format_from_locale/1 returns.
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.
Accepts any shape the locale accepts, including the locale's CLDR short, medium, long and full patterns and ISO 8601.
ISO 8601 is read in every locale: a time between colons, with its
seconds or without them ("14:30:45", "14:30"), and, after its time
designator T, a time without its minutes or without its separators
("T14", "T1430", "T143045"). Digits alone are not read as ISO 8601
without the T: an hour by itself is the locale's to read, and
"1430" is no time. A fraction is the second's alone.
Arguments
stringis a string in any shape the locale accepts, including the locale's CLDR short, medium, long and full patterns and ISO 8601.optionsis a keyword list of options.
Options
:localeis a locale identifier. The default is the locale returned byLocalize.get_locale/0.:calendaris the calendar module the time is written for, whose time formats are read before the Gregorian calendar's. The default isCalendar.ISO. Anything that is not a calendar module, a CLDR calendar type included, is aLocalize.UnknownCalendarError.t/0.:formatis the format the text was written with, asto_string/2takes it: a standard format (:short,:medium,:longor:full), a skeleton atom such as:Hm, aLocalize.DateTime.SemanticSkeletonor a pattern string such as"HH'h'mm". The text is read with that format and no other, ISO 8601 included. A:longor a:fullformat reads a time with its zone and, as it is written for a value that has none, without it, and a semantic skeleton whose minutes are optional reads a time on the hour written without them. The default isnil: the text is read as ISO 8601 or in whichever of the locale's formats reads it first.:asis:structor:map.:mapreturns only the fields the input actually carried, rather than completing them; a minute or second no time has is an error in both forms. A fixed offset (GMT+5) adds theDateTime.t/0zone fields (:time_zone,:utc_offset,:std_offsetand:zone_abbr); a named zone, whose offset depends on a date, stays in:time_zoneas written. The default is:struct.
Returns
{:ok, value}wherevalueis aTime.t/0, or{:error, exception}if the string does not parse, aLocalize.DateTimeFormatErroror aLocalize.DateTimeUnresolvedFormatErrorif:formatis no format of a time, or aLocalize.InvalidValueError.t/0ifstringis not a string or an option is malformed.
Examples
iex> Localize.Time.parse("14:30", locale: :de)
{:ok, ~T[14:30:00]}
iex> Localize.Time.parse("2:30 PM", locale: :en)
{:ok, ~T[14:30:00]}
iex> Localize.Time.parse("T1430", locale: :fi)
{:ok, ~T[14:30:00]}
iex> Localize.Time.parse("14h30", locale: :en, format: "HH'h'mm")
{:ok, ~T[14:30:00]}
@spec strptime(String.t(), String.t(), Keyword.t()) :: {:ok, Time.t()} | {:error, Exception.t()}
Parses a time written with a Calendar.strftime/3 format.
The format is translated into the pattern the locale is read with by
Localize.DateTime.Strptime.pattern/2, and the text read with it by
parse/2, so a time Calendar.strftime/3 writes with
Localize.Calendar.strftime_options!/1 reads back in the same locale,
as does text from C, Python or Ruby. The strptime guide
lists the directives and where the reading differs from C's
strptime(3).
Arguments
stringis the text to parse.formatis aCalendar.strftime/3format string, such as"%I:%M %p".optionsis a keyword list of options.
Options
:preferred_datetime,:preferred_dateand:preferred_timeare the formats%c,%xand%Xstand for, asCalendar.strftime/3takes them.Every option of
parse/2but:format::locale,:calendar, and:as.
Returns
{:ok, time}, asparse/2returns it, or{:error, exception}, aLocalize.DateTimeFormatError.t/0where the format has a directive Localize does not read, aLocalize.InvalidValueError.t/0where the format is not a UTF-8 string or the options are not a keyword list, or the errorparse/2returns where the text does not parse.
Examples
iex> Localize.Time.strptime("7:05 PM", "%I:%M %p", locale: :en)
{:ok, ~T[19:05:00]}
iex> Localize.Time.strptime("07:05:09.250000", "%H:%M:%S.%f", locale: :en)
{:ok, ~T[07:05:09.250000]}
iex> Localize.Time.strptime("14h30", "%Hh%M", locale: :fr)
{: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
timeis aTime.t/0or any map with time keys.optionsis a keyword list of options.
Options
See to_string/2 for the supported options.
Returns
{:ok, parts}wherepartsis 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"}
]}
Same as to_parts/2 but raises on error.
Arguments
timeis aTime.t/0or any map with time keys.optionsis a keyword list of options. Seeto_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
timeis aTime.t/0or any map with one or more of:hour,:minute,:secondkeys.optionsis a keyword list of options.
Options
:formatis a standard format name (:short,:medium,:long,:full), a format skeleton atom, aLocalize.DateTime.SemanticSkeletonor a format pattern string. The default is:mediumfor full times. For a partial time a standard format, or no format, derives its skeleton from the fields present, with the hour in the locale's hour cycle or its-u-hc-override. A value with no time zone, aTime.t/0, aNaiveDateTime.t/0or a map holding neither:time_zonenor:utc_offset, has nothing to write the zone field of:longand:fullwith, so those formats write their other fields as the locale writes them alone:ja's full time is "10:30:00", where a time in Tokyo is "10時30分00秒 日本標準時".:localeis a locale identifier. The default is:en.:number_systemis 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.:numeric_date_separatoris a string replacing the locale'snumericDateSeparatorwherever it separates the fields of a numeric-month date, as TR35 allows an implementation to offer.Localize.DateTime.numeric_separators/2returns the locale's own. The default is the locale's separator.:numeric_time_separatoris a string replacing the locale'snumericTimeSeparatorwherever it separates time fields. The default is the locale's separator.:preferselects between CLDRaltvariants. 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"}
iex> Localize.Time.to_string(%{hour: 14, minute: 30}, locale: :de)
{:ok, "14:30"}
Same as to_string/2 but raises on error.
Arguments
timeis aTime.t/0or any map with one or more of:hour,:minute,:secondkeys.optionsis 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"