Import: time

The time import provides access to the execution time and time functions.

During the execution of a policy the time is fixed to the moment of execution. This gives the illusion that a policy instantly executes at a single moment of time.

The import uses Coordinated Universal Time (UTC).

As an example of this, if a policy accessed time.now.second multiple times, for each access the same value would be returned even if they are several seconds apart. This is the execution timespace, which is mapped to time.now.

It is also possible to run functions on a custom time by using the time.load() function to create a new timespace from the specified value. See the documentation for available actions on timespaces.

Times specified as the reference time or via the time.load() function can be specified in a timeish fashion. This is either one of:

The number of seconds since the Unix epoch (Thursday, 1 January 1970, 00:00:00 UTC),
A timestamp matching the format outlined in RFC3339, either in the format 2006-01-02T15:04:05+07:00, which includes a timezone offset, or 2006-01-02T15:04:05Z, which indicates UTC.

time.now

Create a timespace locked either to execution time or, if set, the reference time. In a given execution, this will always produce the same value.

time.now // {"day": 17, "hour": 23, "minute": 19, "month": 11 ... }

time.load(timeish)

Create a timespace using the given value. Please see the import documentation for valid values for "timeish".

time.load("2019-11-16T01:20:30Z") // {"day": 16, "hour": 1, "minute": 20, "month": 11 ... }

time.nanosecond

A nanosecond duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.nanosecond * 1) // 2019-11-16T01:20:30.000000001Z

time.microsecond

A microsecond duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.microsecond * 1) // 2019-11-16T01:20:30.000001Z

time.millisecond

A millisecond duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.millisecond * 1) // 2019-11-16T01:20:30.001Z

time.second

A second duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.second * 1) // 2019-11-16T01:20:31Z

time.minute

A minute for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.minute * 1) // 2019-11-16T01:21:30Z

time.hour

An hour duration unit for use with the add timespace function.

time.load("2019-11-16T01:20:30Z").add(time.hour * 1) // 2019-11-16T02:20:30Z

Type: timespace

timespace.hour

The hour from 0 to 23.

time.load("2019-11-16T01:20:30Z").hour // 1

timespace.minute

The minute from 0 to 59.

time.load("2019-11-16T01:20:30Z").minute // 20

timespace.second

The second from 0 to 59.

time.load("2019-11-16T01:20:30Z").second // 30

timespace.day

The day of the month, starting from 1.

time.load("2019-11-16T01:20:30Z").day // 16

timespace.month

The month of the year as an integer, starting from 1.

time.load("2019-11-16T01:20:30Z").month // 11

timespace.month_name

The name of the month of the year, in English. Example: January.

time.load("2019-11-16T01:20:30Z").month_name // November

timespace.weekday

The weekday as an integer, where 0 is Sunday and 6 is Saturday.

time.load("2019-11-16T01:20:30Z").weekday // 6

timespace.weekday_name

The name of the day of the week, in English. Example: Sunday.

time.load("2019-11-16T01:20:30Z").weekday_name // Saturday

timespace.year

The year as an integer.

time.load("2019-11-16T01:20:30Z").year // 2019

timespace.unix

The number of seconds since the Unix epoch.

time.load("2019-11-16T01:20:30Z").unix // 1573867230

timespace.unix_nano

The number of nanoseconds since the Unix epoch.

time.load("2019-11-16T01:20:30Z").unix_nano // 1573867230000000000

timespace.zone

The timezone offset, in seconds. This can be a negative number to indicate time west of UTC.

time.load("2019-11-16T01:20:30-08:00").zone // -28800

timespace.zone_string

The timezone offset, in the format +HH:MM (example: -08:00 for PST).

time.load("2019-11-16T01:20:30-08:00").zone_string // -08:00

timespace.before(timeish_or_timespace)

Check if the time in the timespace is before the given time

time.load("2019-11-16T01:20:30Z").before("2019-11-15T01:20:30Z") // false

timespace.after(timeish_or_timespace)

Check if the time in the timespace is after the given time

time.load("2019-11-16T01:20:30Z").after("2019-11-15T01:20:30Z") // true

timespace.equal(timeish_or_timespace)

Check if two times are equivalent

time.load("2019-11-16T01:20:30Z").equal("2019-11-15T01:20:30Z") // false

timespace.add(duration)

Add a duration in nanoseconds to the time in the timespace and return a new timespace. The duration can be negative. The duration should be specified as an integer multiplied with the correct unit.

time.load("2019-11-16T01:20:30Z").add(time.hour * 1) // 2019-11-16T02:20:30Z

timespace.sub(timeish_or_timespace)

Subtract a time from the time in the timespace and return a duration in nanoseconds.

// Gives a duration of 3 hours.
duration = time.load(
    "2019-11-16T01:20:30Z",
).sub("2019-11-16T04:20:30Z")

// Returns 2019-11-16T01:20:30Z
time.load(
    "2019-11-16T04:20:30Z",
).add(duration)