Cldr.Interval.to_string

You're seeing just the function to_string, go back to Cldr.Interval module for more information.

to_string(from, to, backend)

Specs

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 a Date.Range.t 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 [].

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

to_string/3 will decide which formatter to call based upon the aguments provided to it.
- A Date.Range.t will call Cldr.Date.Interval.to_string/3
- A CalendarInterval will call Cldr.Date.Interval.to_string/3 if its :precision is :year, :month or :day. Othersie it will call Cldr.Time.Interval.to_string/3
- If from and to both conform to the Calendar.datetime() type then Cldr.DateTime.Interval.to_string/3 is called
- Otherwise if from and to conform to the Calendar.date() type then Cldr.Date.Interval.to_string/3 is called
- Otherwise if from and to conform to the Calendar.time() type then Cldr.Time.Interval.to_string/3 is called
CalendarInterval support requires adding the dependency calendar_interval to the deps configuration in mix.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 and to 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"}

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

Specs

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

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

to_string/3 will decide which formatter to call based upon the aguments provided to it.
- A Date.Range.t will call Cldr.Date.Interval.to_string/3
- A CalendarInterval will call Cldr.Date.Interval.to_string/3 if its :precision is :year, :month or :day. Othersie it will call Cldr.Time.Interval.to_string/3
- If from and to both conform to the Calendar.datetime() type then Cldr.DateTime.Interval.to_string/3 is called
- Otherwise if from and to conform to the Calendar.date() type then Cldr.Date.Interval.to_string/3 is called
- Otherwise if from and to conform to the Calendar.time() type then Cldr.Time.Interval.to_string/3 is called
CalendarInterval support requires adding the dependency calendar_interval to the deps configuration in mix.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 and to 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 at 12:00:00 AM UTC – December 1, 2020 at 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 at 12:00:00 AM UTC – 10:05:00 AM UTC"}