View Source Cldr.Time.Interval (Cldr Dates & Times v2.20.3)

Interval formats allow for software to format intervals like "Jan 10-12, 2008" as a shorter and more natural format than "Jan 10, 2008 - Jan 12, 2008". They are designed to take a start and end date, time or datetime plus a formatting pattern and use that information to produce a localized format.

See Cldr.Interval.to_string/3 and Cldr.Time.Interval.to_string/3

Summary

Functions

Returns the format code representing the date or time unit that is the greatest difference between two times.

Returns a string representing the formatted interval formed by two times.

Returns a string representing the formatted interval formed by two times.

Functions

Link to this function

greatest_difference(from, to)

View Source

Returns the format code representing the date or time unit that is the greatest difference between two times.

Only differences in hours or minutes are considered.

Arguments

Returns

  • {:ok, format_code} where format_code is one of:

    • :H meaning that the greatest difference is in the hour
    • :m meaning that the greatest difference is in the minute
  • {:error, :no_practical_difference}

Example

iex> Cldr.Time.Interval.greatest_difference ~T[10:11:00], ~T[10:12:00]
{:ok, :m}

iex> Cldr.Time.Interval.greatest_difference ~T[10:11:00], ~T[10:11:00]
{:error, :no_practical_difference}
Link to this function

to_string(from, to, backend, options \\ [])

View Source
@spec to_string(
  Calendar.time() | nil,
  Calendar.time() | nil,
  Cldr.backend(),
  Keyword.t()
) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns a string representing the formatted interval formed by two times.

Arguments

  • from is any map that conforms to the Calendar.time type.

  • to is any map that conforms to the Calendar.time type. to must occur on or after from.

  • backend is any module that includes use Cldr and is therefore Cldr backend module

  • options is a keyword list of options. The default is [format: :medium, style: :time].

Either from or to may also be nil in which case the interval is formatted as an open interval with the non-nil side formatted as a standalone time.

Options

  • :format is one of :short, :medium or :long or a specific format type or a string representing of an interval format. The default is :medium.

  • :style supports different formatting styles. The alternatives are :time, :zone, and :flex. The default is :time.

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0.

  • :number_system a number system into which the formatted date digits should be transliterated.

  • :prefer expresses the preference for one of the possible alternative sub-formats. See the variant preference notes below.

Variant Preference

  • A small number of formats have one of two different alternatives, each with their own preference specifier. The preferences are specified with the :prefer option to Cldr.Date.to_string/3. The preference is expressed as an atom, or a list of one or two atoms with one atom being either :unicode or :ascii and one atom being either :default or :variant.
    • Some formats (at the time of publishng only time formats but that may change in the future) have :unicode and :ascii versions of the format. The difference is the use of ascii space (0x20) as a separateor in the :ascii verison whereas the :unicode version may use non-breaking or other space characters. The default is :unicode and this is the strongly preferred option. The :ascii format is primarily to support legacy use cases and is not recommended. See Cldr.Date.available_formats/3 to see which formats have these variants.

    • Some formats (at the time of publishing, only date and datetime formats) have :default and :variant versions of the format. These variant formats are only included in a small number of locales. For example, the :"en-CA" locale, which has a :default format respecting typical Canadian formatting and a :variant that is more closely aligned to US formatting. The default is :default.

Returns

  • {:ok, string} or

  • {:error, {exception, reason}}

Notes

  • For more information on interval format string see Cldr.Interval.

  • The available predefined formats that can be applied are the keys of the map returned by Cldr.DateTime.Format.interval_formats("en", :gregorian) where "en" can be replaced by any configured locale name and :gregorian is the underlying CLDR calendar type.

  • In the case where from and to are equal, a single time is formatted instead of an interval.

Examples

iex> Cldr.Time.Interval.to_string ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :short
{:ok, "10 – 10 AM"}

iex> Cldr.Time.Interval.to_string ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :medium
{:ok, "10:00 – 10:03 AM"}

iex> Cldr.Time.Interval.to_string ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :long
{:ok, "10:00 – 10:03 AM"}

iex> Cldr.Time.Interval.to_string ~T[10:00:00], ~T[10:03:00], MyApp.Cldr,
...> format: :long, style: :flex
{:ok, "10:00 – 10:03 in the morning"}

iex> Cldr.Time.Interval.to_string ~U[2020-01-01 00:00:00.0Z], ~U[2020-01-01 10:00:00.0Z],
...> MyApp.Cldr, format: :long, style: :flex
{:ok, "12:00 – 10:00 in the morning"}

iex> Cldr.Time.Interval.to_string ~U[2020-01-01 00:00:00.0Z], nil, MyApp.Cldr,
...> format: :long, style: :flex
{:ok, "12:00:00 AM UTC –"}

iex> Cldr.Time.Interval.to_string ~U[2020-01-01 00:00:00.0Z], ~U[2020-01-01 10:00:00.0Z],
...> MyApp.Cldr, format: :long, style: :zone
{:ok, "12:00 – 10:00 AM Etc/UTC"}

iex> Cldr.Time.Interval.to_string ~T[10:00:00], ~T[10:03:00], MyApp.Cldr,
...> format: :long, style: :flex, locale: "th"
{:ok, "10:00 – 10:03 ในตอนเช้า"}
Link to this function

to_string!(from, to, backend, options \\ [])

View Source

Returns a string representing the formatted interval formed by two times.

Arguments

  • from is any map that conforms to the Calendar.time type.

  • to is any map that conforms to the Calendar.time type.

  • backend is any module that includes use Cldr and is therefore Cldr backend module

  • options is a keyword list of options. The default is [format: :medium, style: :time].

Options

  • :format is one of :short, :medium or :long or a specific format type or a string representing of an interval format. The default is :medium.

  • :style supports different formatting styles. The alternatives are :time, :zone, and :flex. The default is :time.

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag.t/0 struct. The default is Cldr.get_locale/0

  • :number_system a number system into which the formatted date digits should be transliterated.

  • :prefer expresses the preference for one of the possible alternative sub-formats. See the variant preference notes below.

Variant Preference

  • A small number of formats have one of two different alternatives, each with their own preference specifier. The preferences are specified with the :prefer option to Cldr.Date.to_string/3. The preference is expressed as an atom, or a list of one or two atoms with one atom being either :unicode or :ascii and one atom being either :default or :variant.
    • Some formats (at the time of publishng only time formats but that may change in the future) have :unicode and :ascii versions of the format. The difference is the use of ascii space (0x20) as a separateor in the :ascii verison whereas the :unicode version may use non-breaking or other space characters. The default is :unicode and this is the strongly preferred option. The :ascii format is primarily to support legacy use cases and is not recommended. See Cldr.Date.available_formats/3 to see which formats have these variants.

    • Some formats (at the time of publishing, only date and datetime formats) have :default and :variant versions of the format. These variant formats are only included in a small number of locales. For example, the :"en-CA" locale, which has a :default format respecting typical Canadian formatting and a :variant that is more closely aligned to US formatting. The default is :default.

Returns

  • string or

  • raises an exception

Notes

  • For more information on interval format string see Cldr.Interval.

  • The available predefined formats that can be applied are the keys of the map returned by Cldr.DateTime.Format.interval_formats("en", :gregorian) where "en" can be replaced by any configured locale name and :gregorian is the underlying CLDR calendar type.

  • In the case where from and to are equal, a single time is formatted instead of an interval.

Examples

iex> Cldr.Time.Interval.to_string! ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :short
"10 – 10 AM"

iex> Cldr.Time.Interval.to_string! ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :medium
"10:00 – 10:03 AM"

iex> Cldr.Time.Interval.to_string! ~T[10:00:00], ~T[10:03:00], MyApp.Cldr, format: :long
"10:00 – 10:03 AM"

iex> Cldr.Time.Interval.to_string ~T[23:00:00.0Z], ~T[01:01:00.0Z], MyApp.Cldr
{:ok, "11:00 PM – 1:01 AM"}

iex> Cldr.Time.Interval.to_string! ~T[10:00:00], ~T[10:03:00], MyApp.Cldr,
...> format: :long, style: :flex
"10:00 – 10:03 in the morning"

iex> Cldr.Time.Interval.to_string! ~U[2020-01-01 00:00:00.0Z], ~U[2020-01-01 10:00:00.0Z],
...> MyApp.Cldr, format: :long, style: :flex
"12:00 – 10:00 in the morning"

iex> Cldr.Time.Interval.to_string! ~U[2020-01-01 00:00:00.0Z], ~U[2020-01-01 10:00:00.0Z],
...> MyApp.Cldr, format: :long, style: :zone
"12:00 – 10:00 AM Etc/UTC"

iex> Cldr.Time.Interval.to_string! ~T[10:00:00], ~T[10:03:00], MyApp.Cldr,
...> format: :long, style: :flex, locale: "th"
"10:00 – 10:03 ในตอนเช้า"