View Source Timex.Duration (timex v3.7.9)

This module provides a friendly API for working with Erlang timestamps, i.e. {megasecs, secs, microsecs}. In addition, it provides an easy way to wrap the measurement of function execution time (via measure).

Link to this section Summary

Functions

Returns the absolute value of the provided Duration.

Add one Duration to another.

This function determines the difference in time between two timestamps (represented by Duration structs). If the second timestamp is omitted, Duration.now will be used as the reference timestamp. If the first timestamp argument occurs before the second, the resulting measurement will be a negative value.

An alias for Duration.diff/3

Returns the duration since the first day of year 0 to Epoch.

Returns the amount of time since the first day of year 0 to Epoch.

Converts a clock tuple, i.e. {hour, minute, second, microsecond} to a Duration.

Converts an integer value representing days to a Duration

Converts an Erlang timestamp to a Duration

Converts an integer value representing hours to a Duration

Converts an integer value representing microseconds to a Duration

Converts an integer value representing milliseconds to a Duration

Converts an integer value representing minutes to a Duration

Converts an integer value representing seconds to a Duration

Converts a Time to a Duration

Converts an integer value representing weeks to a Duration

Invert a Duration, i.e. a positive duration becomes a negative one, and vice versa

Evaluates fun() and measures the elapsed time.

Evaluates apply(fun, args), and measures execution time.

Evaluates apply(module, fun, args), and measures execution time.

Returns the amount of time since Epoch.

Same as parse/1, but returns the Duration unwrapped, and raises on error

Same as parse/2, but returns the Duration unwrapped, and raises on error

Parses a duration string (in ISO-8601 format) into a Duration struct.

Parses a duration string into a Duration struct, using the provided parser module.

Scale a Duration by some coefficient value, i.e. a scale of 2 is twice is long.

Subtract one Duration from another.

Converts a Duration to a clock tuple, i.e. {hour,minute,second,microsecond}.

Converts a Duration to its value in days

Converts a Duration to an Erlang timestamp

Converts a Duration to its value in hours

Converts a Duration to its value in microseconds

Converts a Duration to its value in milliseconds

Converts a Duration to its value in minutes

Converts a Duration to its value in seconds

Converts a Duration to a string, using the ISO standard for formatting durations.

Same as to_time/1, but returns the Time directly. Raises an error if the duration does not fit within a 24-hour clock.

Converts a Duration to a Time if the duration fits within a 24-hour clock. If it does not, an error tuple is returned.

Converts a Duration to its value in weeks

Return a timestamp representing a time lapse of length 0.

Link to this section Types

@type measurement_units() ::
  :microseconds | :milliseconds | :seconds | :minutes | :hours
@type t() :: %Timex.Duration{
  megaseconds: integer(),
  microseconds: integer(),
  seconds: integer()
}
@type to_options() :: [{:truncate, boolean()}]
@type units() ::
  :microsecond
  | :microseconds
  | :millisecond
  | :milliseconds
  | :second
  | :seconds
  | :minutes
  | :hours
  | :days
  | :weeks

Link to this section Functions

@spec abs(t()) :: t()

Returns the absolute value of the provided Duration.

example

Example

iex> d = %Timex.Duration{megaseconds: -1, seconds: -2, microseconds: -3}
...> Timex.Duration.abs(d)
%Timex.Duration{megaseconds: 1, seconds: 2, microseconds: 3}
Link to this function

add(duration1, duration2)

View Source
@spec add(t(), t()) :: t()

Add one Duration to another.

examples

Examples

iex> d = %Timex.Duration{megaseconds: 1, seconds: 1, microseconds: 1}
...> Timex.Duration.add(d, d)
%Timex.Duration{megaseconds: 2, seconds: 2, microseconds: 2}

iex> d = %Timex.Duration{megaseconds: 1, seconds: 750000, microseconds: 750000}
...> Timex.Duration.add(d, d)
%Timex.Duration{megaseconds: 3, seconds: 500001, microseconds: 500000}
Link to this function

diff(t1, t2, type \\ nil)

View Source

This function determines the difference in time between two timestamps (represented by Duration structs). If the second timestamp is omitted, Duration.now will be used as the reference timestamp. If the first timestamp argument occurs before the second, the resulting measurement will be a negative value.

The type argument is an atom indicating the units the measurement should be returned in. If no type argument is provided, a Duration will be returned.

Valid measurement units for this function are:

:microseconds, :milliseconds, :seconds, :minutes, :hours, :days, or :weeks

examples

Examples

iex> alias Timex.Duration
...> d = Duration.from_erl({1457, 136000, 785000})
...> Duration.diff(d, Duration.zero, :days)
16865
Link to this function

elapsed(duration, ref \\ nil, type \\ nil)

View Source

An alias for Duration.diff/3

@spec epoch() :: t()

Returns the duration since the first day of year 0 to Epoch.

example

Example

iex> Timex.Duration.epoch()
%Timex.Duration{megaseconds: 62_167, seconds: 219_200, microseconds: 0}
@spec epoch(nil) :: t()
@spec epoch(units()) :: non_neg_integer()

Returns the amount of time since the first day of year 0 to Epoch.

The argument is an atom indicating the type of time units to return.

The allowed unit type atoms are:

  • :microseconds
  • :milliseconds
  • :seconds
  • :minutes
  • :hours
  • :days
  • :weeks

examples

Examples

iex> Timex.Duration.epoch(:seconds)
62_167_219_200

If the specified type is nil, a duration since the first day of year 0 to Epoch is returned.

iex> Timex.Duration.epoch(nil)
%Timex.Duration{megaseconds: 62_167, seconds: 219_200, microseconds: 0}

Converts a clock tuple, i.e. {hour, minute, second, microsecond} to a Duration.

example

Example

iex> Timex.Duration.from_clock({1, 2, 3, 4})
%Timex.Duration{megaseconds: 0, seconds: 3723, microseconds: 4}
@spec from_days(integer() | float()) :: t()

Converts an integer value representing days to a Duration

@spec from_erl(Timex.Types.timestamp()) :: t()

Converts an Erlang timestamp to a Duration

example

Example

iex> Timex.Duration.from_erl({1, 2, 3})
%Timex.Duration{megaseconds: 1, seconds: 2, microseconds: 3}
@spec from_hours(integer() | float()) :: t()

Converts an integer value representing hours to a Duration

@spec from_microseconds(integer()) :: t()

Converts an integer value representing microseconds to a Duration

@spec from_milliseconds(integer() | float()) :: t()

Converts an integer value representing milliseconds to a Duration

@spec from_minutes(integer() | float()) :: t()

Converts an integer value representing minutes to a Duration

@spec from_seconds(integer() | float()) :: t()

Converts an integer value representing seconds to a Duration

@spec from_time(Time.t()) :: t()

Converts a Time to a Duration

example

Example

iex> Timex.Duration.from_time(~T[01:01:30])
%Timex.Duration{megaseconds: 0, seconds: 3690, microseconds: 0}
@spec from_weeks(integer() | float()) :: t()

Converts an integer value representing weeks to a Duration

@spec invert(t()) :: t()

Invert a Duration, i.e. a positive duration becomes a negative one, and vice versa

example

Example

iex> d = %Timex.Duration{megaseconds: -1, seconds: -2, microseconds: -3}
...> Timex.Duration.invert(d)
%Timex.Duration{megaseconds: 1, seconds: 2, microseconds: 3}
@spec measure((() -> any())) :: {t(), any()}

Evaluates fun() and measures the elapsed time.

Returns {Duration.t, result}.

example

Example

iex> {_timestamp, result} = Duration.measure(fn -> 2 * 2 end)
...> result == 4
true
@spec measure((... -> any()), [any()]) :: {t(), any()}

Evaluates apply(fun, args), and measures execution time.

Returns {Duration.t, result}.

example

Example

iex> {_timestamp, result} = Duration.measure(fn x, y -> x * y end, [2, 4])
...> result == 8
true
Link to this function

measure(module, fun, args)

View Source
@spec measure(module(), atom(), [any()]) :: {t(), any()}

Evaluates apply(module, fun, args), and measures execution time.

Returns {Duration.t, result}.

example

Example

iex> {_timestamp, result} = Duration.measure(Enum, :map, [[1,2], &(&1*2)])
...> result == [2, 4]
true
@spec now(nil) :: t()
@spec now(units()) :: non_neg_integer()

Returns the amount of time since Epoch.

The argument is an atom indicating the type of time units to return.

The allowed unit type atoms are:

  • :microsecond(s)
  • :millisecond(s)
  • :second(s)
  • :minutes
  • :hours
  • :days
  • :weeks

examples

Examples

iex> Timex.Duration.now(:seconds)
1483141644

When the argument is omitted or nil, a Duration is returned.

iex> Timex.Duration.now
%Timex.Duration{megaseconds: 1483, seconds: 141562, microseconds: 536938}
@spec parse!(String.t()) :: t() | no_return()

Same as parse/1, but returns the Duration unwrapped, and raises on error

@spec parse!(String.t(), module()) :: t() | no_return()

Same as parse/2, but returns the Duration unwrapped, and raises on error

@spec parse(String.t()) :: {:ok, t()} | {:error, term()}

Parses a duration string (in ISO-8601 format) into a Duration struct.

@spec parse(String.t(), module()) :: {:ok, t()} | {:error, term()}

Parses a duration string into a Duration struct, using the provided parser module.

@spec scale(t(), coefficient :: integer() | float()) :: t()

Scale a Duration by some coefficient value, i.e. a scale of 2 is twice is long.

example

Example

iex> d = %Timex.Duration{megaseconds: 1, seconds: 1, microseconds: 1}
...> Timex.Duration.scale(d, 2)
%Timex.Duration{megaseconds: 2, seconds: 2, microseconds: 2}
Link to this function

sub(duration1, duration2)

View Source
@spec sub(t(), t()) :: t()

Subtract one Duration from another.

example

Example

iex> d1 = %Timex.Duration{megaseconds: 3, seconds: 3, microseconds: 3}
...> d2 = %Timex.Duration{megaseconds: 2, seconds: 2, microseconds: 2}
...> Timex.Duration.sub(d1, d2)
%Timex.Duration{megaseconds: 1, seconds: 1, microseconds: 1}

Converts a Duration to a clock tuple, i.e. {hour,minute,second,microsecond}.

example

Example

iex> d = %Timex.Duration{megaseconds: 1, seconds: 1, microseconds: 50}
...> Timex.Duration.to_clock(d)
{277, 46, 41, 50}
@spec to_days(t()) :: float()

Converts a Duration to its value in days

example

Example

iex> Duration.to_days(Duration.from_hours(6))
0.25
iex> Duration.to_days(Duration.from_hours(25), truncate: true)
1
@spec to_days(t(), to_options()) :: float() | integer()
@spec to_days(integer() | float(), :microseconds) :: float()
@spec to_days(integer() | float(), :milliseconds) :: float()
@spec to_days(integer() | float(), :seconds) :: float()
@spec to_days(integer() | float(), :minutes) :: float()
@spec to_days(integer() | float(), :hours) :: float()
@spec to_days(integer() | float(), :days) :: float()
@spec to_days(integer() | float(), :weeks) :: float()
@spec to_erl(t()) :: Timex.Types.timestamp()

Converts a Duration to an Erlang timestamp

example

Example

iex> d = %Timex.Duration{megaseconds: 1, seconds: 2, microseconds: 3}
...> Timex.Duration.to_erl(d)
{1, 2, 3}
@spec to_hours(t()) :: float()

Converts a Duration to its value in hours

example

Example

iex> Duration.to_hours(Duration.from_minutes(105))
1.75
iex> Duration.to_hours(Duration.from_minutes(105), truncate: true)
1
@spec to_hours(t(), to_options()) :: float() | integer()
@spec to_hours(integer() | float(), :microseconds) :: float()
@spec to_hours(integer() | float(), :milliseconds) :: float()
@spec to_hours(integer() | float(), :seconds) :: float()
@spec to_hours(integer() | float(), :minutes) :: float()
@spec to_hours(integer() | float(), :hours) :: float()
@spec to_hours(integer() | float(), :days) :: float()
@spec to_hours(integer() | float(), :weeks) :: float()
Link to this function

to_microseconds(duration)

View Source
@spec to_microseconds(t()) :: integer()

Converts a Duration to its value in microseconds

example

Example

iex> Duration.to_microseconds(Duration.from_milliseconds(10.5))
10_500
Link to this function

to_microseconds(duration, arg2)

View Source
@spec to_microseconds(t(), to_options()) :: integer()
@spec to_microseconds(integer() | float(), :microseconds) :: float()
@spec to_microseconds(integer() | float(), :milliseconds) :: float()
@spec to_microseconds(integer() | float(), :seconds) :: float()
@spec to_microseconds(integer() | float(), :minutes) :: float()
@spec to_microseconds(integer() | float(), :hours) :: float()
@spec to_microseconds(integer() | float(), :days) :: float()
@spec to_microseconds(integer() | float(), :weeks) :: float()
@spec to_milliseconds(t()) :: float()

Converts a Duration to its value in milliseconds

example

Example

iex> Duration.to_milliseconds(Duration.from_seconds(1))
1000.0
iex> Duration.to_milliseconds(Duration.from_seconds(1.543))
1543.0
iex> Duration.to_milliseconds(Duration.from_seconds(1.543), truncate: true)
1543
Link to this function

to_milliseconds(d, arg2)

View Source
@spec to_milliseconds(t(), to_options()) :: float() | integer()
@spec to_milliseconds(integer() | float(), :microseconds) :: float()
@spec to_milliseconds(integer() | float(), :milliseconds) :: float()
@spec to_milliseconds(integer() | float(), :seconds) :: float()
@spec to_milliseconds(integer() | float(), :minutes) :: float()
@spec to_milliseconds(integer() | float(), :hours) :: float()
@spec to_milliseconds(integer() | float(), :days) :: float()
@spec to_milliseconds(integer() | float(), :weeks) :: float()
@spec to_minutes(t()) :: float()

Converts a Duration to its value in minutes

example

Example

iex> Duration.to_minutes(Duration.from_seconds(90))
1.5
iex> Duration.to_minutes(Duration.from_seconds(65), truncate: true)
1
@spec to_minutes(t(), to_options()) :: float() | integer()
@spec to_minutes(integer() | float(), :microseconds) :: float()
@spec to_minutes(integer() | float(), :milliseconds) :: float()
@spec to_minutes(integer() | float(), :seconds) :: float()
@spec to_minutes(integer() | float(), :minutes) :: float()
@spec to_minutes(integer() | float(), :hours) :: float()
@spec to_minutes(integer() | float(), :days) :: float()
@spec to_minutes(integer() | float(), :weeks) :: float()
@spec to_seconds(t()) :: float()

Converts a Duration to its value in seconds

example

Example

iex> Duration.to_seconds(Duration.from_milliseconds(1500))
1.5
iex> Duration.to_seconds(Duration.from_milliseconds(1500), truncate: true)
1
@spec to_seconds(t(), to_options()) :: float() | integer()
@spec to_seconds(integer() | float(), :microseconds) :: float()
@spec to_seconds(integer() | float(), :milliseconds) :: float()
@spec to_seconds(integer() | float(), :seconds) :: float()
@spec to_seconds(integer() | float(), :minutes) :: float()
@spec to_seconds(integer() | float(), :hours) :: float()
@spec to_seconds(integer() | float(), :days) :: float()
@spec to_seconds(integer() | float(), :weeks) :: float()
@spec to_string(t()) :: String.t()

Converts a Duration to a string, using the ISO standard for formatting durations.

examples

Examples

iex> d = %Timex.Duration{megaseconds: 0, seconds: 3661, microseconds: 0}
...> Timex.Duration.to_string(d)
"PT1H1M1S"

iex> d = %Timex.Duration{megaseconds: 102, seconds: 656013, microseconds: 33}
...> Timex.Duration.to_string(d)
"P3Y3M3DT3H33M33.000033S"
@spec to_time!(t()) :: Time.t() | no_return()

Same as to_time/1, but returns the Time directly. Raises an error if the duration does not fit within a 24-hour clock.

examples

Examples

iex> d = %Timex.Duration{megaseconds: 0, seconds: 4000, microseconds: 0}
...> Timex.Duration.to_time!(d)
~T[01:06:40]

iex> d = %Timex.Duration{megaseconds: 1, seconds: 0, microseconds: 0}
...> Timex.Duration.to_time!(d)
** (ArgumentError) cannot convert {277, 46, 40} to time, reason: :invalid_time
@spec to_time(t()) :: {:ok, Time.t()} | {:error, atom()}

Converts a Duration to a Time if the duration fits within a 24-hour clock. If it does not, an error tuple is returned.

examples

Examples

iex> d = %Timex.Duration{megaseconds: 0, seconds: 4000, microseconds: 0}
...> Timex.Duration.to_time(d)
{:ok, ~T[01:06:40]}

iex> d = %Timex.Duration{megaseconds: 1, seconds: 0, microseconds: 0}
...> Timex.Duration.to_time(d)
{:error, :invalid_time}
@spec to_weeks(t()) :: float()

Converts a Duration to its value in weeks

example

Example

iex> Duration.to_weeks(Duration.from_days(14))
2.0
iex> Duration.to_weeks(Duration.from_days(13), truncate: true)
1
@spec to_weeks(t(), to_options()) :: float() | integer()
@spec to_weeks(integer() | float(), :microseconds) :: float()
@spec to_weeks(integer() | float(), :milliseconds) :: float()
@spec to_weeks(integer() | float(), :seconds) :: float()
@spec to_weeks(integer() | float(), :minutes) :: float()
@spec to_weeks(integer() | float(), :hours) :: float()
@spec to_weeks(integer() | float(), :days) :: float()
@spec to_weeks(integer() | float(), :weeks) :: float()
@spec zero() :: t()

Return a timestamp representing a time lapse of length 0.

iex> Timex.Duration.zero |> Timex.Duration.to_seconds
0.0

Can be useful for operations on collections of durations. For instance,

Enum.reduce(durations, Duration.zero, Duration.add(&1, &2))

Can also be used to represent the timestamp of the start of the UNIX epoch, as all Erlang timestamps are relative to this point.