Cldr.Interval (Cldr Dates & Times v2.25.3)

View Source

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.

The interval functions in the library will determine the calendar field with the greatest difference between the two datetimes before using the format pattern.

For example, the greatest difference in "Jan 10-12, 2008" is the day field, while the greatest difference in "Jan 10 - Feb 12, 2008" is the month field. This is used to pick the exact format pattern to be used.

Interval Formats

CLDR provides a three-level mapping to a concrete format pattern.

  • The first level determines which fields are included in the interval format. This level is called a format style.

  • The second level is grouped by standard formats (:long, :medium, :short) which reflect the length of the specified fields - espeially the format length of the month field for dates.

  • The third level is a format skeleton which can then be resolved to a format pattern.

Here's an example of the format styles, encapsulating standard formats the resolve to format skeletons.

iex> Cldr.Date.Interval.styles()
%{
  date: %{long: :yMMMEd, medium: :yMMMd, short: :yMd},
  month: %{long: :MMM, medium: :MMM, short: :M},
  month_and_day: %{long: :MMMEd, medium: :MMMd, short: :Md},
  year_and_month: %{long: :yMMMM, medium: :yMMM, short: :yM}
}

# The *time* interval styles are also segments by whether 12-hour
# or 24-hour time formatting is requested.
iex> Cldr.Time.Interval.styles()
%{
  flex: %{h12: %{long: :Bhm, medium: :Bhm, short: :Bh}, h23: %{long: :Bhm, medium: :Bhm, short: :Bh}},
  time: %{h12: %{long: :hm, medium: :hm, short: :h}, h23: %{long: :Hm, medium: :Hm, short: :H}},
  zone: %{h12: %{long: :hmv, medium: :hmv, short: :hv}, h23: %{long: :Hmv, medium: :Hmv, short: :Hv}}
}

Here the format style is the key of the map. For a date they keys are :date, :month, :month_and_day and year_and_month. These are then mapped to one of the standard interval formats :short, :medium or :long returning a format skeleton.

Interval formats

In a manner similar to formatting discrete dates, times and date_times, standard formats are introduced to simplify common usage. For all intervals the following standard formats are:

  • :short
  • :medium (the default)
  • :long

In each case, the mapping is from a format style to a standard format which then resolves to a format skeleton. The format skeleton is then used to resolve a format pattern for the interval.

These maps can be examined as follows where "en" is any configured locale name and :gregorian is the underlying CLDR calendar type. In common use the :gregorian calendar is the standard. However other calendar types are also supported. For example:

iex> Cldr.known_calendars()
[:buddhist, :chinese, :coptic, :dangi, :ethiopic, :ethiopic_amete_alem,
 :gregorian, :hebrew, :indian, :islamic, :islamic_civil, :islamic_rgsa,
 :islamic_tbla, :islamic_umalqura, :japanese, :persian, :roc]

To examine the available interval formats, Cldr.DateTime.Format.interval_formats/2 can be used although its use is primarily internal to the implementation of to_string/3 and would not normally be called directly.

Cldr.DateTime.Format.interval_formats(:en, :gregorian)
=> {:ok,
     %{
       Bh: %{
         B: ["h B – ", "h B"],
         h: ["h – ", "h B"]
       },
       Bhm: %{
         B: ["h:mm B – ", "h:mm B"],
         h: ["h:mm – ", "h:mm B"],
         m: ["h:mm – ", "h:mm B"]
       },
       Gy: %{
         G: ["y G – ", "y G"],
         y: ["y – ", "y G"]
       },
       GyM: %{
         G: ["M/y G – ", "M/y G"],
         M: ["M/y – ", "M/y G"],
         y: ["M/y – ", "M/y G"]
       },
       GyMEd: %{
         G: ["E, M/d/y G – ", "E, M/d/y G"],
         M: ["E, M/d/y – ", "E, M/d/y G"],
         d: ["E, M/d/y – ", "E, M/d/y G"],
         y: ["E, M/d/y – ", "E, M/d/y G"]
       },
       ...
     }
   }

At this point we can see that the path to resolving a format (using the :en locale for this example) is:

  • Apply the format style. For dates, this is :date, returning %{long: :yMMMEd, medium: :yMMMd, short: :yMd}
  • Apply the standard format. For dates, the default is :medium returning the format skeleton :yMMMd.
  • Using the returned format skeleton, resolve the interval formats returning:
%{
   d: ["MMM d – ", "d, y"],
   m: ["MMM d – ", "MMM d, y"],
   y: ["MMM d, y – ", "MMM d, y"]
 }

The field with the greatest difference

There remains one more choice to make - and that choice is made based upon the highest order date field that is different between the from and to dates.

With two dates 2020-02-02 and 2021-01-01 the highest order difference is :year. With 2020-02-02 and 2020-01-01 it is :month.

Formatting the interval

Using this greatest difference information we can now resolve the final format. With the :year field being the greatest difference then the format is y: ["MMM d, y – ", "MMM d, y"].

Finally, formatting can proceed for the from date being formatted with the "MMM d, y – " format pattern and the to date being formatted with the "MMM d, y" format pattern and the two results then being concatenated to form the final string.

Other ways to specify an interval format

So far we have considered formats that are resolved from standard styles and stamdard formats. This is the typical usage and they are specified as parameters to the to_string/3 function. For example:

iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr
{:ok, "Jan 1 – 12, 2020"}

iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr, format: :long
{:ok, "Wed, Jan 1 – Sun, Jan 12, 2020"}

iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> style: :month_and_day
{:ok, "Jan 1 – 12"}

Direct use of format skeletons

It is also possible to directly specify a format skeleton. For example:

iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr, format: :GyMMMd
{:ok, "Jan 1 – 12, 2020 AD"}

Using format patterns

In the unusual situation where one of the standard formats and format skeletons does not meet requirements, a format pattern can also be specified. For example:

iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: "E, M/d/y – E, M/d/y"
{:ok, "Wed, 1/1/2020 – Sun, 1/12/2020"}

In this case, the steps to formatting are:

  1. Split the format pattern at the point at which the first repeating formatting code is detected. In the pattern above it is where the second E is detected. The result in this case will be ["E, M/d/y – ", "E, M/d/y"] For the purposes of splitting, duplicates are ignored. Therefore "EEE, M/d/y – E, M/d/y" will split into ["EEE, M/d/y – ", "E, M/d/y"].

  2. Each part of the pattern is parsed.

  3. The two dates, times or date_times are formatted.

This is a more expensive operation than using the standard formats and styles since the underlying formats for these types are precompiled into an efficient runtime format.

Configuring precompiled interval formats

If there is a requirement for repeated use of format strings then they can be configured in the backend module so that they are precompiled and therefore not suffer a runtime performance penalty.

In a backend module, configure the required formats as a list under the :precompile_interval_formats key:

defmodule MyApp.Cldr do
  use Cldr,
    locales: ["en", "fr"],
    default_locale: "en",
    precompile_interval_formats: ["E, MMM d/y – d/y"]
end

Summary

Types

datetime()

Any date, time or datetime

range()

A Date.Range or CalendarInterval range

Functions

to_string(from, to, backend)

Returns a Date.Range.t/0 or CalendarInterval.t/0 as a localised string.

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

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

to_string!(range, backend, options)

Returns a Date.Range.t/0 or CalendarInterval.t/0 as a localised string or raises an exception.

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

Returns a string representing the formatted interval formed by two dates or raises an exception.

Types

datetime()

@type datetime() ::
  Calendar.date()
  | Calendar.datetime()
  | Calendar.naive_datetime()
  | Calendar.time()

Any date, time or datetime

range()

@type range() :: Date.Range.t() | CalendarInterval.t()

A Date.Range or CalendarInterval range

Functions

to_string(from, to, backend)

@spec to_string(range(), Cldr.backend(), Keyword.t()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns a Date.Range.t/0 or CalendarInterval.t/0 as a localised string.

Arguments

  • range is either a Date.Range.t/0 returned from Date.range/2 or a CalendarInterval.t.

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

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

Options

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

  • :style supports different formatting styles. The valid styles depends on whether formatting is for a date, time or date_time. Since the functions in this module will make a determination as to which formatter to be used based upon the data passed to them it is recommended the style option be omitted. If styling is important then call to_string/3 directly on Cldr.Date.Interval, Cldr.Time.Interval or Cldr.DateTime.Interval.

    • For a date the alternatives are :date, :month_and_day, :month and :year_and_month. The default is :date.

    • For a time the alternatives are :time, :zone and :flex. The default is :time.

    • For a date_time there are no style options, the default for each of the date and time parts is used.

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

Returns

  • {:ok, string} or

  • {:error, {exception, reason}}

Notes

Examples

iex> Cldr.Interval.to_string(Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr,
...> format: :long)
{:ok, "Wed, Jan 1 – Sun, Jan 12, 2020"}

iex> use CalendarInterval
iex> Cldr.Interval.to_string(~I"2020-01-01/12", MyApp.Cldr,
...> format: :long)
{:ok, "Wed, Jan 1 – Sun, Jan 12, 2020"}

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

@spec to_string(datetime(), datetime(), Cldr.backend(), Keyword.t()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

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

Arguments

  • from is any map that conforms to the any one of the Calendar types.

  • to is any map that conforms to the any one of the Calendar types. to must occur on or after from.

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

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

Options

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

  • :style supports different formatting styles. The valid styles depends on whether formatting is for a date, time or datetime. Since the functions in this module will make a determination as to which formatter to be used based upon the data passed to them it is recommended the style option be omitted. If styling is important then call to_string/3 directly on Cldr.Date.Interval, Cldr.Time.Interval or Cldr.DateTime.Interval.

    • For a date the alternatives are :date, :month_and_day, :month and :year_and_month. The default is :date.

    • For a time the alternatives are :time, :zone and :flex. The default is :time.

    • For a datetime there are no style options, the default for each of the date and time part is used.

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

Returns

  • {:ok, string} or

  • {:error, {exception, reason}}

Notes

Examples

iex> Cldr.Interval.to_string(~D[2020-01-01], ~D[2020-12-31], MyApp.Cldr)
{:ok, "Jan 1 – Dec 31, 2020"}

iex> Cldr.Interval.to_string(~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr)
{:ok, "Jan 1 – 12, 2020"}

iex> Cldr.Interval.to_string(~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :long)
{:ok, "Wed, Jan 1 – Sun, Jan 12, 2020"}

iex> Cldr.Interval.to_string(~D[2020-01-01], ~D[2020-12-01], MyApp.Cldr,
...> format: :long, style: :year_and_month)
{:ok, "January – December 2020"}

iex> Cldr.Interval.to_string(~U[2020-01-01 00:00:00.0Z], ~U[2020-12-01 10:05:00.0Z],
...> MyApp.Cldr, format: :long)
{:ok, "January 1, 2020, 12:00:00 AM UTC – December 1, 2020, 10:05:00 AM UTC"}

iex> Cldr.Interval.to_string(~U[2020-01-01 00:00:00.0Z], ~U[2020-01-01 10:05:00.0Z],
...> MyApp.Cldr, format: :long)
{:ok, "January 1, 2020, 12:00:00 AM UTC – 10:05:00 AM UTC"}

iex> Cldr.Interval.to_string(~N[2025-10-05 14:50:00], ~N[2025-10-05 16:30:00],
...> format: :short)
{:ok, "10/5/25, 2:50 PM – 4:30 PM"}

iex> Cldr.Interval.to_string(~N[2025-10-05 14:50:00], ~N[2025-10-05 16:30:00],
...> format: :medium)
{:ok, "Oct 5, 2025, 2:50:00 PM – 4:30:00 PM"}

to_string!(range, backend, options)

@spec to_string!(range(), Cldr.backend(), Keyword.t()) :: String.t() | no_return()

Returns a Date.Range.t/0 or CalendarInterval.t/0 as a localised string or raises an exception.

Arguments

  • range is either a Date.Range.t/0 returned from Date.range/2 or a CalendarInterval.t.

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

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

Options

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

  • :style supports different formatting styles. The valid styles depends on whether formatting is for a date, time or datetime. Since the functions in this module will make a determination as to which formatter to be used based upon the data passed to them it is recommended the style option be omitted. If styling is important then call to_string/3 directly on Cldr.Date.Interval, Cldr.Time.Interval or Cldr.DateTime.Interval.

    • For a date the alternatives are :date, :month_and_day, :month and :year_and_month. The default is :date.

    • For a time the alternatives are :time, :zone and :flex. The default is :time.

    • For a date_time there are no style options, the default for each of the date and time part is used.

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

Returns

  • formatted_string or

  • raises an exception.

Notes

Examples

iex> use CalendarInterval
iex> Cldr.Interval.to_string!(~I"2020-01-01/12", MyApp.Cldr,
...> format: :long)
"Wed, Jan 1 – Sun, Jan 12, 2020"

iex> Cldr.Interval.to_string!(Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr,
...> format: :long)
"Wed, Jan 1 – Sun, Jan 12, 2020"

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

@spec to_string!(datetime(), datetime(), Cldr.backend(), Keyword.t()) ::
  String.t() | no_return()

Returns a string representing the formatted interval formed by two dates or raises an exception.

Arguments

  • from is any map that conforms to the any one of the Calendar types.

  • to is any map that conforms to the any one of the Calendar types. to must occur on or after from.

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

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

Options

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

  • :style supports different formatting styles. The valid styles depends on whether formatting is for a date, time or datetime. Since the functions in this module will make a determination as to which formatter to be used based upon the data passed to them it is recommended the style option be omitted. If styling is important then call to_string/3 directly on Cldr.Date.Interval, Cldr.Time.Interval or Cldr.DateTime.Interval.

    • For a date the alternatives are :date, :month_and_day, :month and :year_and_month. The default is :date.

    • For a time the alternatives are :time, :zone and :flex. The default is :time.

    • For a date_time there are no style options, the default for each of the date and time part is used.

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

Returns

  • formatted_string or

  • raises an exception.

Notes

Examples

iex> Cldr.Interval.to_string!(~D[2020-01-01], ~D[2020-12-31], MyApp.Cldr)
"Jan 1 – Dec 31, 2020"

iex> Cldr.Interval.to_string!(~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr)
"Jan 1 – 12, 2020"

iex> Cldr.Interval.to_string!(~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :long)
"Wed, Jan 1 – Sun, Jan 12, 2020"

iex> Cldr.Interval.to_string!(~D[2020-01-01], ~D[2020-12-01], MyApp.Cldr,
...> format: :long, style: :year_and_month)
"January – December 2020"

iex> Cldr.Interval.to_string!(~U[2020-01-01 00:00:00.0Z], ~U[2020-12-01 10:05:00.0Z],
...> MyApp.Cldr, format: :long)
"January 1, 2020, 12:00:00 AM UTC – December 1, 2020, 10:05:00 AM UTC"

iex> Cldr.Interval.to_string!(~U[2020-01-01 00:00:00.0Z], ~U[2020-01-01 10:05:00.0Z],
...> MyApp.Cldr, format: :long)
"January 1, 2020, 12:00:00 AM UTC – 10:05:00 AM UTC"