Oban.Period (Oban v2.24.1)

Periods represent durations of time as either raw seconds or a unit tuple.

All periods are normalized to seconds internally. The tuple format provides a more expressive way to specify durations in larger units:

# Raw seconds
60

# Unit tuple
{1, :minute}
{5, :minutes}
{2, :hours}

Supported time units are :second, :minute, :hour, :day, :week, :month, and a plural variant of each.

Summary

Types

t()

A time duration as seconds or a unit tuple.

time_unit()

Supported time units for period tuples.

Functions

is_seconds(seconds)

Checks whether the given value is a non-negative integer suitable for seconds.

is_valid_period(period)

Checks whether the given value is a valid period, either seconds or a unit tuple.

to_milliseconds(period)

Convert a period to milliseconds.

to_seconds(seconds)

Convert a period to seconds.

Types

t()

(since 2.20.0)

@type t() :: pos_integer() | {pos_integer(), time_unit()}

A time duration as seconds or a unit tuple.

time_unit()

(since 2.20.0)

@type time_unit() ::
  :second
  | :seconds
  | :minute
  | :minutes
  | :hour
  | :hours
  | :day
  | :days
  | :week
  | :weeks
  | :month
  | :months

Supported time units for period tuples.

Both singular and plural forms are accepted, e.g. :minute and :minutes.

Functions

is_seconds(seconds)

(since 2.20.0) (macro)

Checks whether the given value is a non-negative integer suitable for seconds.

is_valid_period(period)

(since 2.20.0) (macro)

Checks whether the given value is a valid period, either seconds or a unit tuple.

to_milliseconds(period)

(since 2.20.0)

@spec to_milliseconds(t()) :: pos_integer()

Convert a period to milliseconds.

Unlike to_seconds/1, a bare integer is considered milliseconds and returned unchanged; only unit tuples are expanded.

Examples

iex> Oban.Period.to_milliseconds(1000)
1000

iex> Oban.Period.to_milliseconds({1, :second})
1000

iex> Oban.Period.to_milliseconds({2, :minutes})
120_000

to_seconds(seconds)

(since 2.20.0)

@spec to_seconds(t()) :: pos_integer()

Convert a period to seconds.

Examples

iex> Oban.Period.to_seconds(60)
60

iex> Oban.Period.to_seconds({1, :minute})
60

iex> Oban.Period.to_seconds({2, :hours})
7200