Cldr Calendars v1.2.0 Cldr.Calendar.Duration View Source
Functions to create and format a difference between two dates, times or datetimes.
The difference between two dates (or times or datetimes) is usually defined in terms of days or seconds.
A duration is calculated as the difference in time in calendar units: years, months, days, hours, minutes, seconds and microseconds.
This is useful to support formatting a string for users in
easy-to-understand terms. For example 11 months, 3 days and 4 minutes
is a lot easier to understand than 28771440
seconds.
The package ex_cldr_units can be optionally configured to provide localized formatting of durations.
If configured, the following providers should be configured in the appropriate CLDR backend module. For example:
defmodule MyApp.Cldr do
use Cldr,
locales: ["en", "ja"],
providers: [Cldr.Calendar, Cldr.Number, Cldr.Unit, Cldr.List]
end
Link to this section Summary
Functions
Calculates the calendar difference between two dates
returning a Duration
struct.
Calculates the calendar difference between two dates
returning a Duration
struct.
Returns a string formatted representation of a duration.
Formats a duration as a string or raises an exception on error.
Link to this section Types
date_or_datetime()
View Sourcedate_or_datetime() :: Calendar.date() | Calendar.time() | Calendar.datetime()
A date, time or datetime
t()
View Sourcet() :: %Cldr.Calendar.Duration{ day: non_neg_integer(), hour: non_neg_integer(), microsecond: non_neg_integer(), minute: non_neg_integer(), month: non_neg_integer(), second: non_neg_integer(), year: non_neg_integer() }
Measure a duration in calendar units
Link to this section Functions
new(from, to)
View Sourcenew(from :: date_or_datetime(), to :: date_or_datetime()) :: {:ok, t()} | {:error, {module(), String.t()}}
Calculates the calendar difference between two dates
returning a Duration
struct.
The difference calculated is in terms of years, months, days, hours, minutes, seconds and microseconds.
Arguments
from
is a date, time or datetime representing the start of the durationto
is a date, time or datetime representing the end of the duration
Note that from
must be before or at the same time
as to
. In addition, both from
and to
must
be in the same calendar.
Returns
A
{:ok, duration struct}
tuple or a{:error, {exception, reason}}
tuple
Example
iex> Cldr.Calendar.Duration.new(~D[2019-01-01], ~D[2019-12-31])
{:ok,
%Cldr.Calendar.Duration{
year: 0,
month: 11,
day: 30,
hour: 0,
microsecond: 0,
minute: 0,
second: 0
}}
new!(from, to)
View Sourcenew!(from :: date_or_datetime(), to :: date_or_datetime()) :: t() | no_return()
Calculates the calendar difference between two dates
returning a Duration
struct.
The difference calculated is in terms of years, months, days, hours, minutes, seconds and microseconds.
Arguments
from
is a date, time or datetime representing the start of the durationto
is a date, time or datetime representing the end of the duration
Note that from
must be before or at the same time
as to
. In addition, both from
and to
must
be in the same calendar.
Returns
A
duration
struct orraises an exception
Example
iex> Cldr.Calendar.Duration.new!(~D[2019-01-01], ~D[2019-12-31])
%Cldr.Calendar.Duration{
year: 0,
month: 11,
day: 30,
hour: 0,
microsecond: 0,
minute: 0,
second: 0
}
Returns a string formatted representation of a duration.
Note that time units that are zero are ommitted from the output.
Formatting is
Arguments
duration
is a duration of typet()
returned byCldr.Calendar.Duration.new/2
options
is a Keyword list of options
Options
:except
is a list of time units to be omitted from the formatted output. It may be useful to useexcept: [:microsecond]
for example. The default is[]
.locale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct returned byCldr.Locale.new!/2
The default isCldr.get_locale/0
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend/0
:list_options
is a list of options passed toCldr.List.to_string/3
to control the final list output.
Any other options are passed to Cldr.Number.to_string/3
and
Cldr.Unit.to_string/3
during the formatting process.
Example
iex> {:ok, duration} = Cldr.Calendar.Duration.new(~D[2019-01-01], ~D[2019-12-31])
iex> Cldr.Calendar.Duration.to_string(duration)
{:ok, "11 months and 30 days"}
Formats a duration as a string or raises an exception on error.
Arguments
duration
is a duration of typet()
returned byCldr.Calendar.Duration.new/2
options
is a Keyword list of options
Options
See Cldr.Calendar.Duration.to_string/2
Returns
A formatted string or
raises an exception