timex

v0.19.4

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

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 { megasecs, seconds, microseconds }

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 }

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 it's value in days

to_days(value, atom)
to_hours(timestamp)

Converts a timestamp to it's value in hours

to_hours(value, atom)
to_mins(timestamp)

Converts a timestamp to it's value in minutes

to_mins(value, atom)
to_msecs(ts)

Converts a timestamp to it's value in milliseconds

to_msecs(value, atom)
to_secs(ts)

Converts a timestamp to it's value in seconds

to_secs(value, atom)
to_timestamp(value, atom)
to_usecs(arg)

Converts a timestamp to it's value in microseconds

to_usecs(value, atom)
to_weeks(timestamp)

Converts a timestamp to it's value in weeks

to_weeks(value, atom)
zero()

Return a timestamp representing a time lapse of length 0

Types

units ::
  :usecs |
  :msecs |
  :secs |
  :mins |
  :hours |
  :days |
  :weeks |
  :hms
quantity :: float

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 (:usecs), milliseconds (:msecs), seconds (:secs), minutes (:mins), hours (:hours), days (:days), or weeks (: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 (:usecs), milliseconds (:msecs), seconds (:secs), minutes (:mins), or hours (:hours).

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

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 (:usecs), milliseconds (:msecs), seconds (:secs), minutes (:mins), 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 | Date.time, units) :: Date.timestamp

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

Example

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

Specs

measure((() -> any)) :: {Date.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]) :: {Date.timestamp, any}

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

measure(module, fun, args)

Specs

measure(module, atom, [any]) :: {Date.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(Date.timestamp) :: quantity

Converts a timestamp to it's value in days

to_days(value, atom)

Specs

to_days({quantity, quantity, quantity}, :hms) :: quantity
to_days(quantity, :weeks) :: quantity
to_days(quantity, :days) :: quantity
to_days(quantity, :hours) :: quantity
to_days(quantity, :mins) :: quantity
to_days(quantity, :secs) :: quantity
to_days(quantity, :msecs) :: quantity
to_days(quantity, :usecs) :: quantity
to_hours(timestamp)

Specs

to_hours(Date.timestamp) :: quantity

Converts a timestamp to it's value in hours

to_hours(value, atom)

Specs

to_hours({quantity, quantity, quantity}, :hms) :: quantity
to_hours(quantity, :weeks) :: quantity
to_hours(quantity, :days) :: quantity
to_hours(quantity, :hours) :: quantity
to_hours(quantity, :mins) :: quantity
to_hours(quantity, :secs) :: quantity
to_hours(quantity, :msecs) :: quantity
to_hours(quantity, :usecs) :: quantity
to_mins(timestamp)

Specs

to_mins(Date.timestamp) :: quantity

Converts a timestamp to it's value in minutes

to_mins(value, atom)

Specs

to_mins({quantity, quantity, quantity}, :hms) :: quantity
to_mins(quantity, :weeks) :: quantity
to_mins(quantity, :days) :: quantity
to_mins(quantity, :hours) :: quantity
to_mins(quantity, :mins) :: quantity
to_mins(quantity, :secs) :: quantity
to_mins(quantity, :msecs) :: quantity
to_mins(quantity, :usecs) :: quantity
to_msecs(ts)

Specs

to_msecs(Date.timestamp) :: quantity

Converts a timestamp to it's value in milliseconds

to_msecs(value, atom)

Specs

to_msecs({quantity, quantity, quantity}, :hms) :: quantity
to_msecs(quantity, :weeks) :: quantity
to_msecs(quantity, :days) :: quantity
to_msecs(quantity, :hours) :: quantity
to_msecs(quantity, :mins) :: quantity
to_msecs(quantity, :secs) :: quantity
to_msecs(quantity, :msecs) :: quantity
to_msecs(quantity, :usecs) :: quantity
to_secs(ts)

Specs

to_secs(Date.timestamp) :: quantity

Converts a timestamp to it's value in seconds

to_secs(value, atom)

Specs

to_secs({quantity, quantity, quantity}, :hms) :: quantity
to_secs(quantity, :weeks) :: quantity
to_secs(quantity, :days) :: quantity
to_secs(quantity, :hours) :: quantity
to_secs(quantity, :mins) :: quantity
to_secs(quantity, :secs) :: quantity
to_secs(quantity, :msecs) :: quantity
to_secs(quantity, :usecs) :: quantity
to_timestamp(value, atom)
to_usecs(arg)

Specs

to_usecs(Date.timestamp) :: quantity

Converts a timestamp to it's value in microseconds

to_usecs(value, atom)

Specs

to_usecs({quantity, quantity, quantity}, :hms) :: quantity
to_usecs(quantity, :weeks) :: quantity
to_usecs(quantity, :days) :: quantity
to_usecs(quantity, :hours) :: quantity
to_usecs(quantity, :mins) :: quantity
to_usecs(quantity, :secs) :: quantity
to_usecs(quantity, :msecs) :: quantity
to_usecs(quantity, :usecs) :: quantity
to_weeks(timestamp)

Specs

to_weeks(Date.timestamp) :: quantity

Converts a timestamp to it's value in weeks

to_weeks(value, atom)

Specs

to_weeks({quantity, quantity, quantity}, :hms) :: quantity
to_weeks(quantity, :weeks) :: quantity
to_weeks(quantity, :days) :: quantity
to_weeks(quantity, :hours) :: quantity
to_weeks(quantity, :mins) :: quantity
to_weeks(quantity, :secs) :: quantity
to_weeks(quantity, :msecs) :: quantity
to_weeks(quantity, :usecs) :: quantity
zero()

Return a timestamp representing a time lapse of length 0.

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

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

Enum.reduce timestamps, Time.zero, Time.add(&1, &2)