timex v3.1.3 Timex.Duration

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).

Summary

Types

measurement_units()

t()

to_options()

units()

Functions

abs(duration)

Returns the absolute value of the provided Duration

add(duration1, duration2)

Add one Duration to another

diff(t1, t2, type \\ nil)

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

elapsed(duration)

An alias for Duration.diff/3

elapsed(duration, ref)

See Timex.Duration.diff/2

elapsed(duration, ref, type)

See Timex.Duration.diff/3

epoch()

Return time interval since the first day of year 0 to Epoch

epoch(type)

from_clock(arg)

Convers a clock tuple, i.e. {hour,minute,second,microsecond} to a Duration Helpful for if you want to convert a duration to a clock and vice vera

from_days(d)

Converts an integer value representing days to a Duration

from_erl(arg)

Converts an Erlang timestamp to a Duration

from_hours(h)

Converts an integer value representing hours to a Duration

from_microseconds(us)

Converts an integer value representing microseconds to a Duration

from_milliseconds(ms)

Converts an integer value representing milliseconds to a Duration

from_minutes(m)

Converts an integer value representing minutes to a Duration

from_seconds(s)

Converts an integer value representing seconds to a Duration

from_time(t)

Converts a Time to a Duration

from_weeks(w)

Converts an integer value representing weeks to a Duration

invert(duration)

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

measure(fun)

Evaluates fun() and measures the elapsed time

measure(fun, args)

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

measure(module, fun, args)

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

now(type \\ nil)

Time interval since Epoch

parse(str)

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

parse(str, module)

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

parse!(str)

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

parse!(str, module)

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

scale(duration, coef)

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

sub(duration1, duration2)

Subtract one Duration from another

to_clock(duration)

Converts a Duration to a clock tuple, i.e. {hour,minute,second,microsecond} Helpful for if you want to convert a duration to a clock and vice versa

to_days(d)

Converts a Duration to its value in days

to_days(d, arg2)

to_erl(d)

Converts a Duration to an Erlang timestamp

to_hours(d)

Converts a Duration to its value in hours

to_hours(d, arg2)

to_microseconds(duration)

Converts a Duration to its value in microseconds

to_microseconds(duration, arg2)

to_milliseconds(d)

Converts a Duration to its value in milliseconds

to_milliseconds(d, arg2)

to_minutes(d)

Converts a Duration to its value in minutes

to_minutes(d, arg2)

to_seconds(d)

Converts a Duration to its value in seconds

to_seconds(d, arg2)

to_string(duration)

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

to_time(d)

Converts a Duration to a Time, if the duration fits within a 24-hour clock, if it does not, an error will be returned

to_time!(d)

Same as to_time/1, but returns the Time directly, and raises on error

to_weeks(d)

Converts a Duration to its value in weeks

to_weeks(d, arg2)

zero()

Return a timestamp representing a time lapse of length 0

Types

measurement_units()

measurement_units ::
  :microseconds |
  :milliseconds |
  :seconds |
  :minutes |
  :hours

t()

t :: %Timex.Duration{megaseconds: integer, microseconds: integer, seconds: integer}

to_options()

to_options :: [{:truncate, boolean}]

units()

units ::
  :microseconds |
  :milliseconds |
  :seconds |
  :minutes |
  :hours |
  :days |
  :weeks

Functions

abs(duration)

abs(Timex.Duration.t) :: Timex.Duration.t

Returns the absolute value of the provided Duration.

add(duration1, duration2)

add(Timex.Duration.t, Timex.Duration.t) :: Timex.Duration.t

Add one Duration to another.

diff(t1, t2, type \\ nil)

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, or :weeks

Examples

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

elapsed(duration)

An alias for Duration.diff/3

elapsed(duration, ref)

See Timex.Duration.diff/2.

elapsed(duration, ref, type)

See Timex.Duration.diff/3.

epoch()

epoch :: Timex.Duration.t

Return time interval since the first day of year 0 to Epoch.

epoch(type)

epoch(units) :: Timex.Duration.t

from_clock(arg)

Convers a clock tuple, i.e. {hour,minute,second,microsecond} to a Duration Helpful for if you want to convert a duration to a clock and vice vera

from_days(d)

from_days(integer) :: Timex.Duration.t

Converts an integer value representing days to a Duration

from_erl(arg)

from_erl(Timex.Types.timestamp) :: Timex.Duration.t

Converts an Erlang timestamp to a Duration

from_hours(h)

from_hours(integer) :: Timex.Duration.t

Converts an integer value representing hours to a Duration

from_microseconds(us)

from_microseconds(integer) :: Timex.Duration.t

Converts an integer value representing microseconds to a Duration

from_milliseconds(ms)

from_milliseconds(integer) :: Timex.Duration.t

Converts an integer value representing milliseconds to a Duration

from_minutes(m)

from_minutes(integer) :: Timex.Duration.t

Converts an integer value representing minutes to a Duration

from_seconds(s)

from_seconds(integer) :: Timex.Duration.t

Converts an integer value representing seconds to a Duration

from_time(t)

from_time(Time.t) :: Timex.Duration.t

Converts a Time to a Duration

from_weeks(w)

from_weeks(integer) :: Timex.Duration.t

Converts an integer value representing weeks to a Duration

invert(duration)

invert(Timex.Duration.t) :: Timex.Duration.t

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

measure(fun)

measure((() -> any)) :: {Timex.Duration.t, any}

Evaluates fun() and measures the elapsed time.

Returns {Duration.t, result}.

Example

iex> {_timestamp, result} = Duration.measure(fn -> 2 * 2 end)
...> result == 4
true

measure(fun, args)

measure((... -> any), [any]) :: {Timex.Duration.t, any}

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

Returns {Duration.t, result}.

Example

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

measure(module, fun, args)

measure(module, atom, [any]) :: {Timex.Duration.t, any}

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

Returns {Duration.t, result}.

Example

iex> {_timestamp, result} = Duration.measure(Enum, :map, [[1,2], &(&1*2)])
...> result == [2, 4]
true

now(type \\ nil)

now(units) :: non_neg_integer

Time interval since Epoch.

The argument is an atom indicating the type of time units to return (see convert/2 for supported values).

When the argument is omitted, the return value’s format is { megasecs, seconds, microsecs }.

parse(str)

parse(String.t) :: {:ok, Timex.Duration.t} | {:error, term}

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

parse(str, module)

parse(String.t, module) ::
  {:ok, Timex.Duration.t} |
  {:error, term}

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

parse!(str)

parse!(String.t) :: Timex.Duration.t | no_return

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

parse!(str, module)

parse!(String.t, module) :: Timex.Duration.t | no_return

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

scale(duration, coef)

scale(Timex.Duration.t, coefficient :: integer | float) :: Timex.Duration.t

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

sub(duration1, duration2)

sub(Timex.Duration.t, Timex.Duration.t) :: Timex.Duration.t

Subtract one Duration from another.

to_clock(duration)

Converts a Duration to a clock tuple, i.e. {hour,minute,second,microsecond} Helpful for if you want to convert a duration to a clock and vice versa

to_days(d)

to_days(Timex.Duration.t) :: float

Converts a Duration to its value in days

Example

iex> Duration.to_days(Duration.from_hours(6))
0.25
iex> Duration.to_days(Duration.from_hours(25), truncate: true)
1

to_days(d, arg2)

to_days(integer | float, :microseconds) :: float

to_days(integer | float, :milliseconds) :: float

to_days(integer | float, :seconds) :: float

to_days(integer | float, :minutes) :: float

to_days(integer | float, :hours) :: float

to_days(integer | float, :days) :: float

to_days(integer | float, :weeks) :: float

to_erl(d)

to_erl(Timex.Duration.t) :: Timex.Types.timestamp

Converts a Duration to an Erlang timestamp

to_hours(d)

to_hours(Timex.Duration.t) :: float

Converts a Duration to its value in hours

Example

iex> Duration.to_hours(Duration.from_minutes(105))
1.75
iex> Duration.to_hours(Duration.from_minutes(105), truncate: true)
1

to_hours(d, arg2)

to_hours(integer | float, :microseconds) :: float

to_hours(integer | float, :milliseconds) :: float

to_hours(integer | float, :seconds) :: float

to_hours(integer | float, :minutes) :: float

to_hours(integer | float, :hours) :: float

to_hours(integer | float, :days) :: float

to_hours(integer | float, :weeks) :: float

to_microseconds(duration)

to_microseconds(Timex.Duration.t) :: integer

Converts a Duration to its value in microseconds

Example

iex> Duration.to_microseconds(Duration.from_milliseconds(10.5))
10_500

to_microseconds(duration, arg2)

to_microseconds(Timex.Duration.t, to_options) :: integer

to_microseconds(integer | float, :microseconds) :: float

to_microseconds(integer | float, :milliseconds) :: float

to_microseconds(integer | float, :seconds) :: float

to_microseconds(integer | float, :minutes) :: float

to_microseconds(integer | float, :hours) :: float

to_microseconds(integer | float, :days) :: float

to_microseconds(integer | float, :weeks) :: float

to_milliseconds(d)

to_milliseconds(Timex.Duration.t) :: float

Converts a Duration to its value in milliseconds

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

to_milliseconds(d, arg2)

to_milliseconds(Timex.Duration.t, to_options) ::
  float |
  integer

to_milliseconds(integer | float, :microseconds) :: float

to_milliseconds(integer | float, :milliseconds) :: float

to_milliseconds(integer | float, :seconds) :: float

to_milliseconds(integer | float, :minutes) :: float

to_milliseconds(integer | float, :hours) :: float

to_milliseconds(integer | float, :days) :: float

to_milliseconds(integer | float, :weeks) :: float

to_minutes(d)

to_minutes(Timex.Duration.t) :: float

Converts a Duration to its value in minutes

Example

iex> Duration.to_minutes(Duration.from_seconds(90))
1.5
iex> Duration.to_minutes(Duration.from_seconds(65), truncate: true)
1

to_minutes(d, arg2)

to_minutes(Timex.Duration.t, to_options) :: float | integer

to_minutes(integer | float, :microseconds) :: float

to_minutes(integer | float, :milliseconds) :: float

to_minutes(integer | float, :seconds) :: float

to_minutes(integer | float, :minutes) :: float

to_minutes(integer | float, :hours) :: float

to_minutes(integer | float, :days) :: float

to_minutes(integer | float, :weeks) :: float

to_seconds(d)

to_seconds(Timex.Duration.t) :: float

Converts a Duration to its value in seconds

Example

iex> Duration.to_seconds(Duration.from_milliseconds(1500))
1.5
iex> Duration.to_seconds(Duration.from_milliseconds(1500), truncate: true)
1

to_seconds(d, arg2)

to_seconds(Timex.Duration.t, to_options) :: float | integer

to_seconds(integer | float, :microseconds) :: float

to_seconds(integer | float, :milliseconds) :: float

to_seconds(integer | float, :seconds) :: float

to_seconds(integer | float, :minutes) :: float

to_seconds(integer | float, :hours) :: float

to_seconds(integer | float, :days) :: float

to_seconds(integer | float, :weeks) :: float

to_string(duration)

to_string(Timex.Duration.t) :: String.t

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

to_time(d)

to_time(Timex.Duration.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 will be returned.

to_time!(d)

to_time!(Timex.Duration.t) :: Time.t | no_return

Same as to_time/1, but returns the Time directly, and raises on error

to_weeks(d)

to_weeks(Timex.Duration.t) :: float

Converts a Duration to its value in weeks

Example

iex> Duration.to_weeks(Duration.from_days(14))
2.0
iex> Duration.to_weeks(Duration.from_days(13), truncate: true)
1

to_weeks(d, arg2)

to_weeks(integer | float, :microseconds) :: float

to_weeks(integer | float, :milliseconds) :: float

to_weeks(integer | float, :seconds) :: float

to_weeks(integer | float, :minutes) :: float

to_weeks(integer | float, :hours) :: float

to_weeks(integer | float, :days) :: float

to_weeks(integer | float, :weeks) :: float

zero()

zero :: Timex.Duration.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.