Tempo.Duration (Tempo v0.5.0)

A calendar-relative duration — a list of {unit, amount} pairs such as [year: 1, month: 6]. Produced by the ISO 8601 parser (P1Y6M), the RRULE encoder (as the FREQ + INTERVAL cadence), and arithmetic helpers in Tempo.Math.

Summary

Types

t()

unit()

Functions

new(components)

Construct a Tempo.Duration.t/0 from a keyword list of {unit, amount} pairs.

new!(components)

Bang variant of new/1.

Types

t()

@type t() :: %Tempo.Duration{time: [{unit(), integer()}]}

unit()

@type unit() ::
  :year
  | :month
  | :week
  | :day
  | :hour
  | :minute
  | :second
  | :day_of_year
  | :day_of_week

Functions

new(components)

@spec new(keyword()) :: {:ok, t()} | {:error, Exception.t()}

Construct a Tempo.Duration.t/0 from a keyword list of {unit, amount} pairs.

Components can be passed in any order; new/1 reorders them coarse-to-fine before building the struct.

Arguments

components is a keyword list of duration units.

Options

Every value must be an integer. Negative values are permitted (reverse-direction duration).

:year is the year count.
:month is the month count.
:week is the week count.
:day is the day count.
:day_of_year is a day-of-year offset (used by RRULE expansion).
:day_of_week is a day-of-week offset (used by RRULE expansion).
:hour is the hour count.
:minute is the minute count.
:second is the second count.

Returns

{:ok, t()} on success.
{:error, reason} when a key is unknown or a value is not an integer.

Examples

iex> {:ok, d} = Tempo.Duration.new(year: 1, month: 6)
iex> d.time
[year: 1, month: 6]

iex> {:ok, d} = Tempo.Duration.new(month: 6, year: 1)
iex> d.time
[year: 1, month: 6]

new!(components)

@spec new!(keyword()) :: t()

Bang variant of new/1.