Tox.Period (tox v0.2.1)

A Period struct and functions.

The Period struct contains the fields year, month, week, day, hour, minute and second. The values for the fields are representing the amount of time for an unit. Expected second, all values are integers equals or greater 0. The filed second can also be a float equals or greate 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]