time module

The original source for this documentation can be found here: https://github.com/google/starlark-go/blob/master/lib/time/time.go

Module time is a Starlark module of time-related functions and types.

Types

The Time and Duration types can be used using the following operators.

duration + duration = duration
duration + time = time
duration - duration = duration
duration / duration = float
duration / int = duration
duration / float = duration
duration // duration = int
duration * int = duration

Time

A Time represents an instant in time with nanosecond precision. The time type has the following attributes:

year: int

The year in which t occurs.

month: int

Month returns the month of the year specified by t.

day: int

Day returns the day of the month specified by t.

hour: int

Hour returns the hour within the day specified by t, in the range [0, 23].

minute: int

Minute returns the minute offset within the hour specified by t, in the range [0, 59].

second: int

Second returns the second offset within the minute specified by t, in the range [0, 59].

nanosecond: int

Nanosecond returns the nanosecond offset within the second specified by t, in the range [0, 999999999].

unix: int

Unix returns t as a Unix time, the number of seconds elapsed since January 1, 1970 UTC. The result does not depend on the location associated with t. Unix-like operating systems often record time as a 32-bit count of seconds, but since the method here returns a 64-bit value it is valid for billions of years into the past or future.

unix_nano: int

Returns t as a Unix time, the number of nanoseconds elapsed since January 1, 1970 UTC. The result is undefined if the Unix time in nanoseconds cannot be represented by an int64 (a date before the year 1678 or after 2262). Note that this means the result of calling UnixNano on the zero Time is undefined. The result does not depend on the location associated with t.

Duration

A Duration represents the elapsed time between two instants as an int64 nanosecond count. The representation limits the largest representable duration to approximately 290 years.

hours: float

Hours returns the duration as a floating point number of hours.

minutes: float

Minutes returns the duration as a floating point number of minutes.

seconds: float

Seconds returns the duration as a floating point number of seconds.

milliseconds: int64

Milliseconds returns the duration as an integer millisecond count.

microseconds: int64

Microseconds returns the duration as an integer microsecond count.

nanoseconds: int64

Nanoseconds returns the duration as an integer nanosecond count.

Constants

The module defines the following constants:

• nanosecond - A Duration representing one nanosecond.

• microsecond - A Duration representing one microsecond.

• millisecond - A duration representing one millisecond.

• second - A Duration representing one second.

• minute - A Duration representing one minute.

• hour - A Duration representing one hour.

Functions

The module defines the following functions.

def from_timestamp(sec: int, nsec: int) -> Time:

Converts the given Unix time corresponding to the number of seconds and (optionally) nanoseconds since January 1, 1970 UTC into an object of type Time. For more details, refer to https://pkg.go.dev/time#Unix.

def is_valid_timezone(loc: str) -> bool:

Reports whether loc is a valid time zone name.

def now() -> Time:

Returns the current local time.

def parse_duration(d: str) -> Duration:

Parses the given duration string. For more details, refer to https://pkg.go.dev/time#ParseDuration.

def parse_time(x: str, format: str = None, location: str = None) -> Time:

Parses the given time string using a specific time format and location. The expected arguments are a time string (mandatory), a time format (optional, set to RFC3339 by default, e.g. "2021-03-22T23:20:50.52Z") and a name of location (optional, set to UTC by default). For more details, refer to https://pkg.go.dev/time#Parse and https://pkg.go.dev/time#ParseInLocation.

def time(year: int, month: int, day: int, hour: int, minute: int, second: int, nanosecond: int, location: str) -> Time:

Returns the Time corresponding to yyyy-mm-dd hh:mm:ss + nsec nanoseconds in the appropriate zone for that time in the given location. All the parameters are optional.