View Source Cldr.Date.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.Date.Interval.to_string/3
.
Summary
Functions
Returns the format code representing the date or time unit that is the greatest difference between two dates.
Returns a Date.Range
or CalendarInterval
as
a localised string.
Returns a localised 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 localised string representing the formatted interval formed by two dates or raises an exception.
Functions
Returns the format code representing the date or time unit that is the greatest difference between two dates.
Arguments
Returns
{:ok, format_code}
whereformat_code
is one of:y
meaning that the greatest difference is in the year:M
meaning that the greatest difference is in the month:d
meaning that the greatest difference is in the day
{:error, :no_practical_difference}
Example
iex> Cldr.Date.Interval.greatest_difference ~D[2022-04-22], ~D[2022-04-23]
{:ok, :d}
iex> Cldr.Date.Interval.greatest_difference ~D[2022-04-22], ~D[2022-04-22]
{:error, :no_practical_difference}
@spec to_string(Cldr.Interval.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 module.options
is a keyword list of options. The default is[format: :medium, style: :date]
.
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:date
,:month_and_day
,:month
and:year_and_month
. The default is:date
.: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.: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 toCldr.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. SeeCldr.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
CalendarInterval
support requires adding the dependency calendar_interval to thedeps
configuration inmix.exs
.For more information on interval format string see the
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
andto
are equal, a single date is formatted instead of an interval.
Examples
iex> Cldr.Date.Interval.to_string Date.range(~D[2020-01-01], ~D[2020-12-31]), MyApp.Cldr
{:ok, "Jan 1 – Dec 31, 2020"}
iex> Cldr.Date.Interval.to_string Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr
{:ok, "Jan 1 – 12, 2020"}
iex> Cldr.Date.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> Cldr.Date.Interval.to_string Date.range(~D[2020-01-01], ~D[2020-12-01]), MyApp.Cldr,
...> format: :long, style: :year_and_month
{:ok, "January – December 2020"}
iex> use CalendarInterval
iex> Cldr.Date.Interval.to_string ~I"2020-01/12", MyApp.Cldr
{:ok, "Jan 1 – Dec 31, 2020"}
iex> Cldr.Date.Interval.to_string Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr,
...> format: :short
{:ok, "1/1/2020 – 1/12/2020"}
iex> Cldr.Date.Interval.to_string Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr,
...> format: :long, locale: "fr"
{:ok, "mer. 1 – dim. 12 janv. 2020"}
@spec to_string( Calendar.date() | nil, Calendar.date() | nil, Cldr.backend(), Keyword.t() ) :: {:ok, String.t()} | {:error, {module(), String.t()}}
Returns a localised string representing the formatted interval formed by two dates.
Arguments
from
is any map that conforms to theCalendar.date
type.to
is any map that conforms to theCalendar.date
type.to
must occur on or afterfrom
.backend
is any module that includesuse Cldr
and is therefore anCldr
backend moduleoptions
is a keyword list of options. The default is[format: :medium, style: :date]
.
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 date.
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:date
,:month_and_day
,:month
and:year_and_month
. The default is:date
.: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.: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 toCldr.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. SeeCldr.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 the
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
andto
are equal, a single date is formatted instead of an interval.
Examples
iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-12-31], MyApp.Cldr
{:ok, "Jan 1 – Dec 31, 2020"}
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-12-01], MyApp.Cldr,
...> format: :long, style: :year_and_month
{:ok, "January – December 2020"}
iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :short
{:ok, "1/1/2020 – 1/12/2020"}
iex> Cldr.Date.Interval.to_string ~D[2020-01-01], nil, MyApp.Cldr,
...> format: :short
{:ok, "1/1/20 –"}
iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :long, locale: "fr"
{:ok, "mer. 1 – dim. 12 janv. 2020"}
iex> Cldr.Date.Interval.to_string ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :long, locale: "th", number_system: :thai
{:ok, "พ. ๑ ม.ค. – อา. ๑๒ ม.ค. ๒๐๒๐"}
@spec to_string!(Cldr.Interval.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]
.
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:date
,:month_and_day
,:month
and:year_and_month
. The default is:date
.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.: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 toCldr.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. SeeCldr.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
orraises an exception
Notes
CalendarInterval
support requires adding the dependency calendar_interval to thedeps
configuration inmix.exs
.For more information on interval format string see the
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
andto
are equal, a single date is formatted instead of an interval.
Examples
iex> Cldr.Date.Interval.to_string! Date.range(~D[2020-01-01], ~D[2020-12-31]), MyApp.Cldr
"Jan 1 – Dec 31, 2020"
iex> Cldr.Date.Interval.to_string! Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr
"Jan 1 – 12, 2020"
iex> Cldr.Date.Interval.to_string! Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr,
...> format: :long
"Wed, Jan 1 – Sun, Jan 12, 2020"
iex> Cldr.Date.Interval.to_string! Date.range(~D[2020-01-01], ~D[2020-12-01]), MyApp.Cldr,
...> format: :long, style: :year_and_month
"January – December 2020"
iex> use CalendarInterval
iex> Cldr.Date.Interval.to_string! ~I"2020-01/12", MyApp.Cldr
"Jan 1 – Dec 31, 2020"
iex> Cldr.Date.Interval.to_string! Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr,
...> format: :short
"1/1/2020 – 1/12/2020"
iex> Cldr.Date.Interval.to_string! Date.range(~D[2020-01-01], ~D[2020-01-12]), MyApp.Cldr,
...> format: :long, locale: "fr"
"mer. 1 – dim. 12 janv. 2020"
@spec to_string!( Calendar.date() | nil, Calendar.date() | nil, Cldr.backend(), Keyword.t() ) :: String.t() | no_return()
Returns a localised string representing the formatted interval formed by two dates or raises an exception.
Arguments
from
is any map that conforms to theCalendar.date
type.to
is any map that conforms to theCalendar.date
type.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]
.
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:date
,:month_and_day
,:month
and:year_and_month
. The default is:date
.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.: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 toCldr.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. SeeCldr.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
orraises 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
andto
are equal, a single date is formatted instead of an interval.
Examples
iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-12-31], MyApp.Cldr
"Jan 1 – Dec 31, 2020"
iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr
"Jan 1 – 12, 2020"
iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :long
"Wed, Jan 1 – Sun, Jan 12, 2020"
iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-12-01], MyApp.Cldr,
...> format: :long, style: :year_and_month
"January – December 2020"
iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :short
"1/1/2020 – 1/12/2020"
iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :long, locale: "fr"
"mer. 1 – dim. 12 janv. 2020"
iex> Cldr.Date.Interval.to_string! ~D[2020-01-01], ~D[2020-01-12], MyApp.Cldr,
...> format: :long, locale: "th", number_system: :thai
"พ. ๑ ม.ค. – อา. ๑๒ ม.ค. ๒๐๒๐"