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

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

Link to this section 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.

Link to this section 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

Arguments

returns

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

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

Specs

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

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 [].

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

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 dfferent 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 struct. The default is Cldr.get_locale/0

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

returns

Returns

  • {:ok, string} or

  • {:error, {exception, reason}}

notes

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

Examples

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

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

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 [].

options

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 dfferent 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 struct. The default is Cldr.get_locale/0

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

returns

Returns

  • string or

  • raises an exception

notes

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

Examples

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

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[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 ในตอนเช้า"