Time functions

Contract / Module:

free.util-time

Dependencies:

free.util-lists
free.util-math
free.util-chain-data

General functions

epoch

→ time

Return Unix EPOCH.

pact> (epoch)
"1970-01-01T00:00:00Z"

genesis

→ time

Return Kadena Genesis time.

pact> (genesis)
"2019-10-30T00:01:00Z"

now

→ time

Return the current time.

pact> (now)
"2022-12-04T14:54:24Z"

tomorrow

→ time

Return the current time + 24 hours.

pact> (tomorrow)
"2022-12-05T14:54:24Z"

yesterday

→ time

Return the current time - 24 hours.

pact> (yesterday)
"2022-12-03T14:54:24Z"

from-now

delta decimal → time

Returns the delta time taking now as a reference.

pact> (from-now (hours 1))
"2022-12-05T15:54:24Z"

today

→ string

Return the current day.

pact> (today)
"2022-12-04"

to-timestamp

in time → decimal

Compute an Unix timestamp of the input date.

pact> (to-timestamp (time "2022-12-05T00:08:53Z"))
1670198933.0

from-timestamp

timestamp decimal → time

Compute a time from an Unix timestamp.

pact> (from-timestamp 1670198933.0)
"2022-12-05T00:08:53Z"

Compare function

earliest

time1 time time2 time → time

Return the earliest time between time1 and time2.

This function is equivalent to a min between two times.

(earliest (time "2022-12-04T14:54:24Z")  (time "2022-12-04T14:44:24Z"))
"2022-12-04T14:44:24Z"

latest

time1 time time2 time → time

Return the earliest time between time1 and time2.

This function is equivalent to a max between two times.

pact> (latest (time "2022-12-04T14:54:24Z")  (time "2022-12-04T14:44:24Z"))
"2022-12-04T14:54:24Z"

time-between

time1 time time2 time in time → bool

Return true if in is between time1 and time2.

The order of time1 and time2 doesn’t matter.

pact> (time-between (time "2022-12-04T14:44:24Z")
....>               (time "2022-12-24T14:44:24Z")
....>               (time "2022-12-08T14:44:24Z"))
true

pact> (time-between (time "2022-12-24T14:44:24Z")
....>               (time "2022-12-04T14:44:24Z")
....>               (time "2022-12-08T14:44:24Z"))
true

pact> (time-between (time "2022-12-24T14:44:24Z")
....>               (time "2022-12-04T14:44:24Z")
....>               (time "2022-12-26T14:44:24Z"))
false

is-past

in time → bool

Return true if in is in the past (before now).

pact> (env-chain-data { 'block-time: (time "2022-12-04T14:54:24Z") })
"Updated public metadata"

pact> (is-past (time "2022-12-04T13:54:24Z"))
true
pact> (is-past (time "2022-12-04T15:54:24Z"))
false

is-future

in time → bool

Return true if in is in the future (after now).

pact> (env-chain-data { 'block-time: (time "2022-12-04T14:54:24Z") })
"Updated public metadata"

pact> (is-future (time "2022-12-04T13:54:24Z"))
false
pact> (is-future (time "2022-12-04T15:54:24Z"))
true

is-today

in time → bool

Return true if in is in the current day.

pact> (env-chain-data { 'block-time: (time "2022-12-04T14:54:24Z") })
"Updated public metadata"
pact> (is-today (time "2022-12-04T13:54:24Z"))
true
pact> (is-today (time "2022-12-05T13:54:24Z"))
false

Block height estimation functions

est-height-at-time

target-time time → integer

Estimates the block height at a target-time.

This function extrapolates the expected block height using the current block height, and the current time.

A block time of 30s is assumed.

This function can used for the future or the past.

If the computed result is a negative block height (before Genesis), 0 is returned.

pact> (est-height-at-time (time "2022-12-04T09:10:30Z"))
3257212

pact> (est-height-at-time (time "2018-01-01T09:10:30Z"))
0

est-time-at-height

target-height integer → time

Estimates the time at a target-block.

This function extrapolates the expected block height using the current block height, and the current time.

A block time of 30s is assumed.

This function can used for the future or the past.

pact> (est-time-at-height 3257212)
"2022-12-04T09:10:43Z"

Time difference functions

diff-time-minutes

time1 time time2 time → decimal

Compute difference between time1 and time2 in minutes.

pact> (diff-time-minutes (time "2022-12-04T14:54:24Z")  (time "2022-12-04T14:44:24Z"))
10.0

diff-time-hours

time1 time time2 time → decimal

Compute difference between time1 and time2 in hours.

pact> (diff-time-hours (time "2022-12-04T14:54:24Z")  (time "2022-12-04T04:54:24Z"))
10.0

diff-time-days

time1 time time2 time → decimal

Compute difference between time1 and time2 in days.

pact> (diff-time-days (time "2022-12-04T14:54:24Z")  (time "2022-12-02T14:54:24Z"))
2.0