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
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
.
Functions
Creates a new period from durations
. All values in the durations
must be
equal or greater 0
.
Creates a new period. All values in durations must be greater or equal 0
.
Creates a new period from durations
or raises an error.
Creates a new period or raise an error.
Creates a new period from a string.
Creates a new period from a string.
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
.
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
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
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
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
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()]
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
.
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]