View Source Cldr.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.
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 pattern to be used.
Interval Formats
CLDR provides a two-level mapping to a concrete format string.
To simplify the developer experience, ex_cldr_dates_times
groups these
mappings into styles
and formats
.
Styles group different CLDR formats into similar types. These styles can be seen by examining the output below:
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}
}
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 style is the key if the map: :date
, :month
,
:month_and_day
and year_and_month
.
These are then mapped to interval formats :short
, :medium
or :long
.
Interval formats
In a manner similar to formatting individual dates, times and datetimes, format types are introduced to simplify common usage. For all intervals the following format types are;
:short
:medium
(the default):long
In each case, the mapping is from a style to a format type and then of resolves to a native CLDR format map.
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 is:
- Apply the format style. For dates, this is
:date
. - Apply the format type. For dates, the default is
:medium
.
This will then return a map such as:
%{
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
"MMM d, y – "
and the to
date being formatted with "MMM d, y"
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 a resolved from standard styles
and format types. 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 CLDR format types
It is also possible to directly specify the CLDR format type. 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 strings
In the unusual situation where one of the standard format styles and types does not meet requirements, a format string 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:
Split the format string 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, duplicate are ignored. Therefore "EEE, M/d/y – E, M/d/y" will split into["EEE, M/d/y – ", "E, M/d/y"]
.Each part of the pattern is parsed.
The two dates, times or datetimes are formatted.
This is a more expensive operation than using the predefined styles and format types 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
Functions
Returns a Date.Range
or CalendarInterval
as
a localised string.
Returns a string representing the formatted interval formed by two dates.
Returns a Date.Range
or CalendarInterval
as
a localised string or raises an exception.
Returns a string representing the formatted interval formed by two dates or raises an exception.
Types
@type datetime() :: Calendar.date() | Calendar.datetime() | Calendar.naive_datetime() | Calendar.time()
Any date, time or datetime
@type range() :: Date.Range.t() | CalendarInterval.t()
A Date.Range or CalendarInterval range
Functions
@spec to_string(range(), Cldr.backend(), Keyword.t()) :: {:ok, String.t()} | {:error, {module(), String.t()}}
Returns a Date.Range
or CalendarInterval
as
a localised string.
Arguments
range
is either aDate.Range.t
returned fromDate.range/2
or aCalendarInterval.t
.backend
is any module that includesuse Cldr
and is therefore aCldr
backend moduleoptions
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 type or a string 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 callto_string/3
directly onCldr.Date.Interval
,Cldr.Time.Interval
orCldr.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 byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.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
to_string/3
will decide which formatter to call based upon the arguments provided to it.A
Date.Range.t
will callCldr.Date.Interval.to_string/3
.A
CalendarInterval
will callCldr.Date.Interval.to_string/3
if its:precision
is:year
,:month
or:day
. Otherwise it will callCldr.Time.Interval.to_string/3
.If
from
andto
both conform to theCalendar.datetime()
type thenCldr.DateTime.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.date()
type thenCldr.Date.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.time()
type thenCldr.Time.Interval.to_string/3
is called.
CalendarInterval
support requires adding the dependency calendar_interval to thedeps
configuration inmix.exs
.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 configuration locale name and:gregorian
is the underlying CLDR calendar type.In the case where
from
andto
are equal, a single date, time or datetime is formatted instead of an interval.
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"}
@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 theCalendar
types.to
is any map that conforms to the any one of theCalendar
types.to
must occur on or afterfrom
.backend
is any module that includesuse Cldr
and is therefore aCldr
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 type or a string 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 callto_string/3
directly onCldr.Date.Interval
,Cldr.Time.Interval
orCldr.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 byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.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
to_string/3
will decide which formatter to call based upon the arguments provided to it.A
Date.Range.t
will callCldr.Date.Interval.to_string/3
.A
CalendarInterval
will callCldr.Date.Interval.to_string/3
if its:precision
is:year
,:month
or:day
. Otherwise it will callCldr.Time.Interval.to_string/3
.If
from
andto
both conform to theCalendar.datetime()
type thenCldr.DateTime.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.date()
type thenCldr.Date.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.time()
type thenCldr.Time.Interval.to_string/3
is called.
CalendarInterval
support requires adding the dependency calendar_interval to thedeps
configuration inmix.exs
.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 configuration locale name and:gregorian
is the underlying CLDR calendar type.In the case where
from
andto
are equal, a single date, time or datetime is formatted instead of an interval.
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"}
@spec to_string!(range(), Cldr.backend(), Keyword.t()) :: String.t() | no_return()
Returns a Date.Range
or CalendarInterval
as
a localised string or raises an exception.
Arguments
range
is either aDate.Range.t
returned fromDate.range/2
or aCalendarInterval.t
.backend
is any module that includesuse Cldr
and is therefore aCldr
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 type or a string 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 callto_string/3
directly onCldr.Date.Interval
,Cldr.Time.Interval
orCldr.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 byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.get_locale/0
.number_system:
a number system into which the formatted date digits should be transliterated.
Returns
string
orraises an exception
Notes
to_string/3
will decide which formatter to call based upon the arguments provided to it.A
Date.Range.t
will callCldr.Date.Interval.to_string/3
.A
CalendarInterval
will callCldr.Date.Interval.to_string/3
if its:precision
is:year
,:month
or:day
. Otherwise it will callCldr.Time.Interval.to_string/3
.If
from
andto
both conform to theCalendar.datetime()
type thenCldr.DateTime.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.date()
type thenCldr.Date.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.time()
type thenCldr.Time.Interval.to_string/3
is called.
CalendarInterval
support requires adding the dependency calendar_interval to thedeps
configuration inmix.exs
.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 configuration locale name and:gregorian
is the underlying CLDR calendar type.In the case where
from
andto
are equal, a single date, time or datetime is formatted instead of an interval.
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"
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 theCalendar
types.to
is any map that conforms to the any one of theCalendar
types.to
must occur on or afterfrom
.backend
is any module that includesuse Cldr
and is therefore aCldr
backend moduleoptions
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 type or a string 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 callto_string/3
directly onCldr.Date.Interval
,Cldr.Time.Interval
orCldr.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 byCldr.known_locale_names/0
or aCldr.LanguageTag.t/0
struct. The default isCldr.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
to_string/3
will decide which formatter to call based upon the arguments provided to it.A
Date.Range.t
will callCldr.Date.Interval.to_string/3
A
CalendarInterval
will callCldr.Date.Interval.to_string/3
if its:precision
is:year
,:month
or:day
. Otherwise it will callCldr.Time.Interval.to_string/3
.If
from
andto
both conform to theCalendar.datetime()
type thenCldr.DateTime.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.date()
type thenCldr.Date.Interval.to_string/3
is called.Otherwise if
from
andto
conform to theCalendar.time()
type thenCldr.Time.Interval.to_string/3
is called.
CalendarInterval
support requires adding the dependency calendar_interval to thedeps
configuration inmix.exs
.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 configuration locale name and:gregorian
is the underlying CLDR calendar type.In the case where
from
andto
are equal, a single date, time or datetime is formatted instead of an interval.
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"