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

NOTE: Due to limitations in the runtime, the following usage scenarios are not supported when using this import:

• Multiple function calls in the same expression, example: time.load(1136239445).before(1136239446).
• Making function calls on a returned timespace. Working off of the above example, if you assigned the first value to t in the form t = time.load(1136239445), t.before(1136239446) will not be supported.

To work within the limitations surrounding function calls, times can be compared by converting them to Unix time using the unix function. These limitations may be addressed in future releases.

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.load(timeish)

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

time.nanosecond

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

time.microsecond

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

time.millisecond

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

time.second

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

time.minute

A minute for use with the add timespace function.

time.hour

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

Type: timespace

timespace.hour

The hour from 0 to 23.

timespace.minute

The minute from 0 to 59.

timespace.second

The second from 0 to 59.

timespace.day

The day of the month, starting from 1.

timespace.month

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

timespace.month_name

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

timespace.weekday

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

timespace.weekday_name

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

timespace.year

The year as an integer.

timespace.unix

The number of seconds since the Unix epoch.

timespace.unix_nano

The number of nanoseconds since the Unix epoch.

timespace.zone

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

timespace.zone_string

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

timespace.before(timeish_or_timespace)

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

timespace.after(timeish_or_timespace)

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

timespace.equal(timeish_or_timespace)

Check if two times are equivalent

timespace.add(duration)

Add a duration 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.

timespace.sub(timeish_or_timespace)

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