timex

v2.1.5

timex v2.1.5 Timex.Time

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

units()

Functions

abs(arg)
add(arg1, arg2)
convert(timestamp, type \\ :timestamp)

Convert timestamp in the form { megasecs, seconds, microsecs } to the specified time units

diff(t1, t2, type \\ :timestamp)

Time interval between two timestamps. If the first timestamp comes before the second one in time, the return value will be negative. Timestamp must be in format

elapsed(timestamp, type \\ :timestamp)

Time interval between timestamp and now. If timestamp is after now in time, the return value will be negative. Timestamp must be in format

elapsed(arg1, arg2, type)
epoch(type \\ :timestamp)

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

from(value, atom)

Converts the given input value and unit to an Erlang timestamp

invert(arg)
measure(fun)

Evaluates fun() and measures the elapsed time

measure(fun, args)

Evaluates apply(fun, args). Otherwise works like measure/1

measure(module, fun, args)

Evaluates apply(module, fun, args). Otherwise works like measure/1

now(type \\ :timestamp)

Time interval since Epoch

scale(arg, coef)
sub(arg1, arg2)
to_12hour_clock(hour)

Converts an hour between 0..24 to {1..12, :am/:pm}

to_24hour_clock(hour, am_or_pm)

Converts an hour between 1..12 in either am or pm, to value between 0..24

to_days(timestamp)

Converts a timestamp to its value in days

to_days(value, atom)
to_hours(timestamp)

Converts a timestamp to its value in hours

to_hours(value, atom)
to_microseconds(arg)

Converts a timestamp to its value in microseconds

to_microseconds(value, atom)
to_milliseconds(ts)

Converts a timestamp to its value in milliseconds

to_milliseconds(value, atom)
to_mins(timestamp)
to_mins(value, type)
to_minutes(timestamp)

Converts a timestamp to its value in minutes

to_minutes(value, atom)
to_msecs(timestamp)
to_msecs(value, type)
to_seconds(ts)

Converts a timestamp to its value in seconds

to_seconds(value, atom)
to_secs(timestamp)
to_secs(value, type)
to_timestamp(value, atom)
to_usecs(timestamp)
to_usecs(value, type)
to_weeks(timestamp)

Converts a timestamp to its value in weeks

to_weeks(value, atom)
zero()

Return a timestamp representing a time lapse of length 0

Types 

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

Functions

abs(arg)
add(arg1, arg2)
convert(timestamp, type \\ :timestamp)

Convert timestamp in the form { megasecs, seconds, microsecs } to the specified time units.

Supported units

  • :microseconds
  • :milliseconds
  • :seconds
  • :minutes
  • :hours
  • :days
  • :weeks
diff(t1, t2, type \\ :timestamp)

Time interval between two timestamps. If the first timestamp comes before the second one in time, the return value will be negative. Timestamp must be in format:

{ megasecs, seconds, microseconds }.

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

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

When the third argument is omitted, the return value’s format is:

{ megasecs, seconds, microsecs }.

Examples

iex> use Timex
...> Time.diff({1457, 136000, 785000}, Time.zero, :days)
16865
elapsed(timestamp, type \\ :timestamp)

Time interval between timestamp and now. If timestamp is after now in time, the return value will be negative. Timestamp must be in format:

{ megasecs, seconds, microseconds }.

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

:microseconds, :milliseconds, :seconds, :minutes, or hours (:hours).

When the second argument is omitted, the return value’s format is

{ megasecs, seconds, microsecs }.
elapsed(arg1, arg2, type)
epoch(type \\ :timestamp)

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

from(value, atom)

Specs

from(integer | Timex.Types.time, units) :: Timex.Types.timestamp

Converts the given input value and unit to an Erlang timestamp.

Example

iex> Timex.Time.from(1500, :seconds)
{0, 1500, 0}
invert(arg)
measure(fun)

Specs

measure((() -> any)) :: {Timex.Types.timestamp, any}

Evaluates fun() and measures the elapsed time.

Returns {timestamp, result}, timestamp is the usual { megasecs, seconds, microsecs }.

Example

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

Specs

measure((... -> any), [any]) :: {Timex.Types.timestamp, any}

Evaluates apply(fun, args). Otherwise works like measure/1

measure(module, fun, args)

Specs

measure(module, atom, [any]) :: {Timex.Types.timestamp, any}

Evaluates apply(module, fun, args). Otherwise works like measure/1

now(type \\ :timestamp)

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

scale(arg, coef)
sub(arg1, arg2)
to_12hour_clock(hour)

Converts an hour between 0..24 to {1..12, :am/:pm}

Examples

iex> Timex.Time.to_12hour_clock(23)
{11, :pm}
to_24hour_clock(hour, am_or_pm)

Converts an hour between 1..12 in either am or pm, to value between 0..24

Examples

iex> Timex.Time.to_24hour_clock(7, :pm)
19
to_days(timestamp)

Specs

to_days(Timex.Types.timestamp) :: float

Converts a timestamp to its value in days

to_days(value, atom)

Specs

to_days({integer | float, integer | float, integer | float}, :hms) :: float
to_days(integer | float, :weeks) :: float
to_days(integer | float, :days) :: float
to_days(integer | float, :hours) :: float
to_days(integer | float, :minutes) :: float
to_days(integer | float, :seconds) :: float
to_days(integer | float, :milliseconds) :: float
to_days(integer | float, :microseconds) :: float
to_hours(timestamp)

Specs

to_hours(Timex.Types.timestamp) :: float

Converts a timestamp to its value in hours

to_hours(value, atom)

Specs

to_hours({integer | float, integer | float, integer | float}, :hms) :: float
to_hours(integer | float, :weeks) :: float
to_hours(integer | float, :days) :: float
to_hours(integer | float, :hours) :: float
to_hours(integer | float, :minutes) :: float
to_hours(integer | float, :seconds) :: float
to_hours(integer | float, :milliseconds) :: float
to_hours(integer | float, :microseconds) :: float
to_microseconds(arg)

Specs

to_microseconds(Timex.Types.timestamp) :: integer

Converts a timestamp to its value in microseconds

to_microseconds(value, atom)

Specs

to_microseconds({integer | float, integer | float, integer | float}, :hms) :: float
to_microseconds(integer | float, :weeks) :: float
to_microseconds(integer | float, :days) :: float
to_microseconds(integer | float, :hours) :: float
to_microseconds(integer | float, :minutes) :: float
to_microseconds(integer | float, :seconds) :: float
to_microseconds(integer | float, :milliseconds) :: float
to_microseconds(integer | float, :microseconds) :: float
to_milliseconds(ts)

Specs

to_milliseconds(Timex.Types.timestamp) :: float

Converts a timestamp to its value in milliseconds

to_milliseconds(value, atom)

Specs

to_milliseconds({integer | float, integer | float, integer | float}, :hms) :: float
to_milliseconds(integer | float, :weeks) :: float
to_milliseconds(integer | float, :days) :: float
to_milliseconds(integer | float, :hours) :: float
to_milliseconds(integer | float, :minutes) :: float
to_milliseconds(integer | float, :seconds) :: float
to_milliseconds(integer | float, :milliseconds) :: float
to_milliseconds(integer | float, :microseconds) :: float
to_mins(timestamp)
to_mins(value, type)
to_minutes(timestamp)

Specs

to_minutes(Timex.Types.timestamp) :: float

Converts a timestamp to its value in minutes

to_minutes(value, atom)

Specs

to_minutes({integer | float, integer | float, integer | float}, :hms) :: float
to_minutes(integer | float, :weeks) :: float
to_minutes(integer | float, :days) :: float
to_minutes(integer | float, :hours) :: float
to_minutes(integer | float, :minutes) :: float
to_minutes(integer | float, :seconds) :: float
to_minutes(integer | float, :milliseconds) :: float
to_minutes(integer | float, :microseconds) :: float
to_msecs(timestamp)
to_msecs(value, type)
to_seconds(ts)

Specs

to_seconds(Timex.Types.timestamp) :: float

Converts a timestamp to its value in seconds

to_seconds(value, atom)

Specs

to_seconds({integer | float, integer | float, integer | float}, :hms) :: float
to_seconds(integer | float, :weeks) :: float
to_seconds(integer | float, :days) :: float
to_seconds(integer | float, :hours) :: float
to_seconds(integer | float, :minutes) :: float
to_seconds(integer | float, :seconds) :: float
to_seconds(integer | float, :milliseconds) :: float
to_seconds(integer | float, :microseconds) :: float
to_secs(timestamp)
to_secs(value, type)
to_timestamp(value, atom)
to_usecs(timestamp)
to_usecs(value, type)
to_weeks(timestamp)

Specs

to_weeks(Timex.Types.timestamp) :: float

Converts a timestamp to its value in weeks

to_weeks(value, atom)

Specs

to_weeks({integer | float, integer | float, integer | float}, :hms) :: float
to_weeks(integer | float, :weeks) :: float
to_weeks(integer | float, :days) :: float
to_weeks(integer | float, :hours) :: float
to_weeks(integer | float, :minutes) :: float
to_weeks(integer | float, :seconds) :: float
to_weeks(integer | float, :milliseconds) :: float
to_weeks(integer | float, :microseconds) :: float
zero()

Return a timestamp representing a time lapse of length 0.

Time.convert(Time.zero, :seconds)
#=> 0

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

Enum.reduce(timestamps, Time.zero, Time.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.