View Source Cldr.Calendar.Duration (Cldr Calendars v1.20.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

A date, time, naivedatetime or datetime

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

t()

Duration in calendar units

Functions

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

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

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

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

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

Returns a string formatted representation of a duration.

Link to this section Types

Link to this type

date_or_time_or_datetime()

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

A date, time, naivedatetime or datetime

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

A interval as either Date.Range.t() CalendarInterval.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

@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

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

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
 }}
@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
 }}
Link to this function

to_string!(duration, options \\ [])

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

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

arguments

Arguments

options

Options

See Cldr.Calendar.Duration.to_string/2

returns

Returns

  • A formatted string or

  • raises an exception

Link to this function

to_string(duration, options \\ [])

View Source

Returns a string formatted representation of a duration.

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

Formatting is

arguments

Arguments

options

Options

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