# `Tempo.Duration`
[🔗](https://github.com/kipcole9/tempo/blob/v0.5.0/lib/tempo/duration.ex#L1)

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

# `t`

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

# `unit`

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

# `new`

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

Construct a `t: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!`

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

Bang variant of `new/1`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*