View Source Cldr.Calendar.Duration (Cldr Calendars v1.22.0)

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

Types

date_or_time_or_datetime()

A date, time, naivedatetime or datetime

interval()

A interval as either Date.Range.t() CalendarInterval.t()

t()

Duration in calendar units

Functions

new(arg1)

Calculates the calendar difference in a Date.Range or CalendarInterval returning a Duration struct.

new(from, to)

Calculates the calendar difference between two dates returning a Duration struct.

new!(interval)

Calculates the calendar difference in a Date.Range or CalendarInterval returning a Duration struct.

new!(from, to)

Calculates the calendar difference between two dates returning a Duration struct.

to_string(duration, options \\ [])

Returns a string formatted representation of a duration.

to_string!(duration, options \\ [])

Formats a duration as a string or raises an exception on error.

Link to this section Types

date_or_time_or_datetime()

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

A date, time, naivedatetime or datetime

interval()

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

A interval as either Date.Range.t() CalendarInterval.t()

t()

@type t() :: %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()
}

Duration in calendar units

Link to this section Functions

new(arg1)

@spec new(interval()) :: {:ok, t()} | {:error, {module(), String.t()}}

Calculates the calendar difference in a Date.Range or CalendarInterval returning a Duration struct.

The difference calculated is in terms of years, months, days, hours, minutes, seconds and microseconds.

arguments
Arguments

interval is either Date.Range.t() or a CalendarInterval.t()

returns
Returns

A {:ok, duration} tuple or a
{:error, {exception, reason}} tuple

notes
Notes

CalendarInterval is defined by the most wonderful calendar_interval library.

example
Example

iex> Cldr.Calendar.Duration.new(Date.range(~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)

@spec new(from :: date_or_time_or_datetime(), to :: date_or_time_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
Arguments

from is a date, time or datetime representing the start of the duration.
to is a date, time or datetime representing the end of the duration

notes
Notes

from must be before or at the same time as to. In addition, both from and to must be in the same calendar
If from and to are datetimes then they must both be in the same time zone

returns
Returns

A {:ok, duration} tuple or a
{:error, {exception, reason}} tuple

example
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!(interval)

@spec new!(interval()) :: t() | no_return()

Calculates the calendar difference in a Date.Range or CalendarInterval returning a Duration struct.

The difference calculated is in terms of years, months, days, hours, minutes, seconds and microseconds.

arguments
Arguments

interval is either Date.Range.t() or a CalendarInterval.t()

returns
Returns

A duration struct or
raises an exception

notes
Notes

CalendarInterval is defined by the most wonderful calendar_interval library.

example
Example

iex> Cldr.Calendar.Duration.new!(Date.range(~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
}

new!(from, to)

@spec new!(from :: date_or_time_or_datetime(), to :: date_or_time_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
Arguments

from is a date, time or datetime representing the start of the duration
to 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
Returns

A duration struct or
raises an exception

example
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
}

to_string(duration, options \\ [])

Returns a string formatted representation of a duration.

Note that time units that are zero are omitted from the output.

Formatting is

arguments
Arguments

duration is a duration of type t() returned by Cldr.Calendar.Duration.new/2
options is a Keyword list of options

options
Options

:except is a list of time units to be omitted from the formatted output. It may be useful to use except: [:microsecond] for example. The default is [].
locale is any valid locale name returned by Cldr.known_locale_names/1 or a Cldr.LanguageTag struct returned by Cldr.Locale.new!/2 The default is Cldr.get_locale/0
backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend/0
:list_options is a list of options passed to Cldr.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.

note
Note

Any duration parts that are 0 are not output.

example
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"}

to_string!(duration, options \\ [])

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

Formats a duration as a string or raises an exception on error.

arguments
Arguments

duration is a duration of type t() returned by Cldr.Calendar.Duration.new/2
options is a Keyword list of options

options
Options

See Cldr.Calendar.Duration.to_string/2

returns
Returns

A formatted string or
raises an exception

Settings View Source Cldr.Calendar.Duration (Cldr Calendars v1.22.0)

Link to this section Summary

Types

Functions

Link to this section Types

date_or_time_or_datetime()

interval()

t()

Link to this section Functions

new(arg1)

arguments Arguments

returns Returns

notes Notes

example Example

new(from, to)

arguments Arguments

notes Notes

returns Returns

example Example

new!(interval)

arguments Arguments

returns Returns

notes Notes

example Example

new!(from, to)

arguments Arguments

returns Returns

example Example

to_string(duration, options \\ [])

arguments Arguments

options Options

note Note

example Example

to_string!(duration, options \\ [])

arguments Arguments

options Options

returns Returns

View Source Cldr.Calendar.Duration (Cldr Calendars v1.22.0)

arguments
Arguments

returns
Returns

notes
Notes

example
Example

arguments
Arguments

notes
Notes

returns
Returns

example
Example

arguments
Arguments

returns
Returns

notes
Notes

example
Example

arguments
Arguments

returns
Returns

example
Example

arguments
Arguments

options
Options

note
Note

example
Example

arguments
Arguments

options
Options

returns
Returns