Tox.Period (tox v0.2.3)

A Period struct and functions.

The Period struct contains the fields year, month, week, day, hour, minute and second. The values for the fields represent the amount of time for a unit. Expected second, all values are integers equal or greater than 0. The field second can also be a float equals to or greater than 0.

Link to this section Summary

Types

duration()

An amount of time with a specified unit e.g. {second: 5.500} or {hour: 1}. The amount of all durations must be equal or greater as 0.

t()

Functions

new(durations)

Creates a new period from durations. All values in the durations must be equal or greater 0.

new(year, month, week, day, hour, minute, second)

Creates a new period. All values in durations must be greater or equal 0.

new!(durations)

Creates a new period from durations or raises an error.

new!(year, month, week, day, hour, minute, second)

Creates a new period or raise an error.

parse(string)

Creates a new period from a string.

parse!(string)

Creates a new period from a string.

to_durations(period, sign \\ :pos)

Returns the period as [Tox.duration]. The optional sign can be :pos for positive durations and :neg for negative durations, defaults to :pos. A duration with an amount of 0 will be excluded form the durations.

Link to this section Types

duration()

Specs

duration() ::
  {:year, non_neg_integer()}
  | {:month, non_neg_integer()}
  | {:week, non_neg_integer()}
  | {:day, non_neg_integer()}
  | {:hour, non_neg_integer()}
  | {:minute, non_neg_integer()}
  | {:second, non_neg_integer()}

An amount of time with a specified unit e.g. {second: 5.500} or {hour: 1}. The amount of all durations must be equal or greater as 0.

t()

Specs

t() :: %Tox.Period{
  day: non_neg_integer(),
  hour: non_neg_integer(),
  minute: non_neg_integer(),
  month: non_neg_integer(),
  second: non_neg_integer() | float(),
  week: non_neg_integer(),
  year: non_neg_integer()
}

Link to this section Functions

new(durations)

Specs

new([duration()]) :: {:ok, t()} | {:error, :invalid_period}

Creates a new period from durations. All values in the durations must be equal or greater 0.

Examples

iex> {:ok, period} = Tox.Period.new(day: 4, hour: 5)
iex> period
#Tox.Period<P4DT5H>

iex> Tox.Period.new(minute: -1)
{:error, :invalid_period}

new(year, month, week, day, hour, minute, second)

Specs

new(
  year :: non_neg_integer(),
  month :: non_neg_integer(),
  week :: non_neg_integer(),
  day :: non_neg_integer(),
  hour :: non_neg_integer(),
  minute :: non_neg_integer(),
  second :: non_neg_integer() | float()
) :: {:ok, t()} | {:error, :invalid_period}

Creates a new period. All values in durations must be greater or equal 0.

Examples

iex> {:ok, period} = Tox.Period.new(1, 2, 3, 4, 5, 6, 7.8)
iex> period
#Tox.Period<P1Y2M3W4DT5H6M7.8S>

iex> Tox.Period.new(1, 2, 3, 4, 5, 6, -7.8)
{:error, :invalid_period}

new!(durations)

Specs

new!([duration()]) :: t()

Creates a new period from durations or raises an error.

See new/1 for more informations.

Examples

iex> Tox.Period.new!(month: 1, minute: 1)
#Tox.Period<P1MT1M>

iex> Tox.Period.new!(year: 0.5)
** (ArgumentError) cannot create a new period with [year: 0.5], reason: :invalid_period

new!(year, month, week, day, hour, minute, second)

Specs

new!(
  year :: non_neg_integer(),
  month :: non_neg_integer(),
  week :: non_neg_integer(),
  day :: non_neg_integer(),
  hour :: non_neg_integer(),
  minute :: non_neg_integer(),
  second :: non_neg_integer() | float()
) :: t()

Creates a new period or raise an error.

See new/7 for more informations.

Examples

iex> Tox.Period.new!(1, 2, 3, 4, 5, 6, 7.8)
#Tox.Period<P1Y2M3W4DT5H6M7.8S>

iex> Tox.Period.new!(1, 2, 3, 4, 5, 6, -7.8)
** (ArgumentError) cannot create a new period with [year: 1, month: 2, week: 3, day: 4, hour: 5, minute: 6, second: -7.8], reason: :invalid_period

parse(string)

Specs

parse(String.t()) :: {:ok, t()} | {:error, :invalid_format}

Creates a new period from a string.

A string representation of a period has the format PiYiMiWiDTiHiMfS. The i represents an integer and the f a float. All integers and the float must be equal or greater as 0. Leading zeros are not required. The capital letters P , Y, M, W, D, T, H, M, and S are designators for each of the date and time elements and are not replaced.

P is the period designator (optional).
- Y is the year designator that follows the value for the number of years.
- M is the month designator that follows the value for the number of months.
- W is the week designator that follows the value for the number of weeks.
- D is the day designator that follows the value for the number of days.
T is the time designator that precedes the time components of the representation.
- H is the hour designator that follows the value for the number of hours.
- M is the minute designator that follows the value for the number of minutes.
- S is the second designator that follows the value for the number of seconds.

Examples

iex> Tox.Period.parse("1Y3M")
Tox.Period.new(year: 1, month: 3)

iex> Tox.Period.parse("T12M5.5S")
Tox.Period.new(minute: 12, second: 5.5)

iex> Tox.Period.parse("P1Y3MT2H")
Tox.Period.new(year: 1, month: 3, hour: 2)

iex> Tox.Period.parse("1y")
{:error, :invalid_format}

parse!(string)

Specs

parse!(String.t()) :: t()

Creates a new period from a string.

See parse/1 for more informations.

Examples

iex> Tox.Period.parse!("T12M5.5S")
#Tox.Period<PT12M5.5S>

iex> Tox.Period.parse!("1y")
** (ArgumentError) cannot parse "1y" as period, reason: :invalid_format

to_durations(period, sign \\ :pos)

Specs

to_durations(t(), :pos | :neg) :: [Tox.duration()]

Examples

iex> {:ok, period} = Tox.Period.parse("P1Y3MT2H1.123S")
iex> Tox.Period.to_durations(period)
[year: 1, month: 3, hour: 2, second: 1, microsecond: 123000]
iex> Tox.Period.to_durations(period, :neg)
[year: -1, month: -3, hour: -2, second: -1, microsecond: -123000]

iex> {:ok, period} = Tox.Period.parse("1MT1M")
iex> Tox.Period.to_durations(period)
[month: 1, minute: 1]