time

Benchmark helpers Errors returned by the benchmark() procedure.

Options for benchmarking.

Type representing duration, with nanosecond precision. This is the regular Unix timestamp, scaled to nanosecond precision.

Type representing a month.

Type representing a stopwatch.

The stopwatch is used for measuring the total time in multiple "runs". When the stopwatch is started, it starts counting time. When the stopwatch is stopped, the difference in time between the last start and the stop is added to the total. When the stopwatch resets, the total is reset.

Type representing monotonic time, useful for measuring durations.

Specifies time since the UNIX epoch, with nanosecond precision.

Capable of representing any time within the following range:

• min: 1677-09-21 00:12:44.145224192 +0000 UTC
• max: 2262-04-11 23:47:16.854775807 +0000 UTC

Type representing a weekday.

i64((ABSOLUTE_ZERO_YEAR - 1) 365.2425 SECONDS_PER_DAY);

Day is chosen so that 2001-01-01 is Monday in the calculations

Days in 100 years, with leap days.

Days in 400 years, with leap days.

Days in 4 years, with leap days.

The duration equal to one hour (3600 seconds).

Value specifying whether the time procedures are supported by the current platform.

Maximum representable duration.

Minimum representable duration.

The duration equal to one microsecond (1e-6 seconds).

The duration equal to one millisecond (1e-3 seconds).

The duration equal to one minute (60 seconds).

The duration equal to one nanosecond (1e-9 seconds).

Number of seconds in a day (without leap seconds).

Number of seconds in an hour (without leap seconds).

Number of seconds in a minute (without leap seconds).

Number of seconds in a week (without leap seconds).

The duration equal to one second.

Days before each month in a year, not counting the leap day on february 29th.

Capture the duration the code in the current scope takes to execute.

Accurate sleep

This procedure sleeps for the duration specified by d, very accurately.

Note: Implementation borrowed from: this source

Note(linux): The accuracy is within around 4µs (microseconds), in the worst case.

Note(windows): The accuracy depends but is comparable with regular sleep in the worst case. To get the same kind of accuracy as on Linux, have your program call windows.timeBeginPeriod(1) to tell Windows to use a more accurate timer for your process. Additionally your program should call windows.timeEndPeriod(1) once you're done with accurate_sleep.

Benchmark a procedure.

This procedure produces a benchmark. The procedure specified in the bench field of the options parameter will be benchmarked. The following metrics can be obtained:

• Run time of the procedure
• Number of elements per second processed on average
• Number of bytes per second this processed on average

In order to obtain these metrics, the bench() procedure writes to options struct the number of elements or bytes it has processed.

Obtain the time components from a duration.

Obtain the time components from the number of seconds.

Obtain the time components from a stopwatch's total.

Obtain the time components from a time.

Convert datetime components into time.

This procedure calculates the time from datetime components supplied in the arguments to this procedure. If the datetime components don't represent a valid datetime, the function returns false in the second argument.

Convert datetime into time.

If the datetime represents a time outside of a valid range, false is returned as the second return value. See Time for the representable range.

Parse time into date components.

Obtain the day of the date specified by time.

Calculate the duration elapsed between two times.

Obtain the number of hours in a duration.

Obtain the number of microseconds in a duration.

Obtain the number of milliseconds in a duration.

Obtain the number of minutes in a duration.

Obtain the number of nanoseconds in a duration.

Round a duration to a specific unit

This procedure rounds the duration to a specific unit

Note: Any duration can be supplied as a unit.

Inputs:

• d: The duration to round
• m: The unit to round to

Returns:

• The duration d, rounded to the unit specified by m

Example:

time.duration_round(my_duration, time.Second)

Obtain the number of seconds in a duration.

Formats a Duration as a 24-hour hh:mm:ss string.

Does not allocate

Inputs:

• d: The Duration to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf

Example:

buf: [MIN_HMS_LEN]u8
d   := time.since(earlier)
fmt.println(time.to_string_hms(now, buf[:]))

Truncate the duration to the specified unit.

This procedure truncates the duration d to the unit specified by m.

Note: Any duration can be supplied as a unit.

Inputs:

• d: The duration to truncate.
• m: The unit to truncate to.

Returns:

• The duration d, truncated to the unit specified by m.

Example:

time.duration_round(my_duration, time.Second)

Obtain time from unix nanoseconds.

Check if the CPU has invariant TSC.

This procedure checks if the CPU contains an invariant TSC (Time stamp counter). Invariant TSC is a feature of modern processors that allows them to run their TSC at a fixed frequency, independent of ACPI state, and CPU frequency.

Check if a year is a leap year.

Parse an ISO 8601 string into a datetime and a UTC offset in minutes.

This procedure parses an ISO 8601 string of roughly the following format:

YYYY-MM-DD[Tt]HH:mm:ss[.nn][Zz][+-]HH:mm

And returns datetime, in UTC represented by that string, and the UTC offset, in minutes.

Inputs:

• iso_datetime: The string to be parsed

Returns:

• res: The parsed datetime, in UTC.
• utc_offset: The UTC offset, in minutes.
• is_leap: Specifies whether the moment was a leap second.
• consumed: The number of bytes consumed by parsing the string.

Notes:

• This procedure performs no validation on whether components are valid,

e.g. it'll return hour = 25 if that's what it's given in the specified string.

Parse an ISO 8601 string into a time and a UTC offset in minutes.

This procedure parses an ISO 8601 string of roughly the following format:

YYYY-MM-DD[Tt]HH:mm:ss[.nn][Zz][+-]HH:mm

And returns time, in UTC represented by that string, and the UTC offset, in minutes.

Inputs:

• iso_datetime: The string to be parsed.
• is_leap: Optional output parameter, specifying if the moment was a leap second.

Returns:

• res: The time in UTC.
• utc_offset: The UTC offset of the time, in minutes.
• consumed: Number of bytes consumed by parsing the string.

Notes:

• Only 4-digit years are accepted.
• Leap seconds are smeared into 23:59:59.

Parse an ISO 8601 string into a time with UTC offset applied to it.

This procedure parses an ISO 8601 string of roughly the following format:

YYYY-MM-DD[Tt]HH:mm:ss[.nn][Zz][+-]HH:mm

And returns time, in UTC represented by that string. In case the timezone offset is specified in the string, that timezone is applied to time.

Inputs:

• iso_datetime: The string to be parsed.
• is_leap: Optional output parameter, specifying if the moment was a leap second.

Returns:

• res: The time represented by iso_datetime, with UTC offset applied.
• consumed: Number of bytes consumed by parsing the string.

Notes:

• Only 4-digit years are accepted.
• Leap seconds are smeared into 23:59:59.

Obtain the month of the date specified by time.

Obtain the current time.

Obtain the time components from a duration, including nanoseconds.

Obtain the time components from a stopwatch's total, including nanoseconds

Obtain the time components from a time, including nanoseconds.

Read the timestamp counter of the CPU.

Parse an RFC 3339 string into a datetime and a UTC offset in minutes.

This procedure parses the specified RFC 3339 strings of roughly the following format:

YYYY-MM-DD[Tt]HH:mm:ss[.nn][Zz][+-]HH:mm

And returns the datetime, in UTC and the UTC offset, in minutes, that were represented by the RFC 3339 string.

Inputs:

• rfc_datetime: The RFC 3339 string to parse.

Returns:

• res: The datetime, in UTC, that was parsed from the RFC 3339 string.
• utc_offset: The UTC offset, in minutes, that was parsed from the RFC 3339

string.

• is_leap: Specifies whether the moment was a leap second.
• consumed: Number of bytes consumed by parsing the string.

Performs no validation on whether components are valid, e.g. it'll return hour = 25 if that's what it's given

Parse an RFC 3339 string into a time and a UTC offset in minutes.

This procedure parses the specified RFC 3339 strings of roughly the following format:

YYYY-MM-DD[Tt]HH:mm:ss[.nn][Zz][+-]HH:mm

And returns the time, in UTC and a UTC offset, in minutes, that were represented by the RFC 3339 string.

Inputs:

• rfc_datetime: The RFC 3339 string to be parsed.
• is_leap: Optional output parameter specifying whether the moment was a

leap second.

Returns:

• res: The time, in UTC, that was parsed from the RFC 3339 string.
• utc_offset: The UTC offset, in minutes, that was parsed from the RFC 3339

string.

• consumed: The number of bytes consumed by parsing the string.

Notes:

• Only 4-digit years are accepted.
• Leap seconds are smeared into 23:59:59.

Parse an RFC 3339 string into time with a UTC offset applied to it.

This procedure parses the specified RFC 3339 strings of roughly the following format:

YYYY-MM-DD[Tt]HH:mm:ss[.nn][Zz][+-]HH:mm

And returns the time that was represented by the RFC 3339 string, with the UTC offset applied to it.

Inputs:

• rfc_datetime: An RFC 3339 string to parse.
• is_leap: Optional output parameter specifying whether the moment was a leap

second.

Returns:

• res: The time, with UTC offset applied, that was parsed from the RFC 3339

string.

• consumed: The number of bytes consumed by parsing the RFC 3339 string.

Notes:

• Only 4-digit years are accepted.
• Leap seconds are smeared into 23:59:59.

Calculate the duration elapsed since a specific time.

Sleep for the specified duration.

Obtain the total time, counted by the stopwatch.

This procedure obtains the total time, counted by the stopwatch. If the stopwatch isn't stopped at the time of calling this procedure, the time between the last start and the current time is also accounted for.

Reset the stopwatch.

Start the stopwatch.

Stop the stopwatch.

Add duration to a tick.

Obtain the difference between ticks.

Incrementally obtain durations since last tick.

This procedure returns the duration between the current tick and the tick stored in prev pointer, and then stores the current tick in location, specified by prev. If the prev pointer contains an zero-initialized tick, then the returned duration is 0.

This procedure is meant to be used in a loop, or in other scenarios, where one might want to obtain time between multiple ticks at specific points.

Obtain the current tick.

Obtain the duration since last tick.

Add duration to a time.

Alias for time_to_datetime.

Convert time into datetime.

Serialize the timestamp as a RFC 3339 string.

The boolean ok is false if the time is not a valid datetime, or if allocating the result string fails.

Inputs:

• utc_offset: offset in minutes wrt UTC (ie. the timezone)
• include_nanos: whether to include nanoseconds in the result.

Formats a Time as a 24-hour hh:mm:ss string.

Does not allocate

Inputs:

• t: The Time to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf

Example:

buf: [MIN_HMS_LEN]u8
now := time.now()
fmt.println(time.to_string_hms(now, buf[:]))

Obtain the Unix timestamp in seconds from a Time.

Obtain the Unix timestamp in nanoseconds from a Time.

Formats a Time as a dd-mm-yy date string.

Inputs:

• t: The Time to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf.

Example:

buf: [MIN_YY_DATE_LEN]u8
now := time.now()
fmt.println(time.to_string_dd_mm_yy(now, buf[:]))

Formats a Time as a dd-mm-yyyy date string.

Inputs:

• t: The Time to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf.

Example:

buf: [MIN_YYYY_DATE_LEN]u8
now := time.now()
fmt.println(time.to_string_dd_mm_yyyy(now, buf[:]))

Formats a Time as a 12-hour hh:mm:ss pm string

Does not allocate

Inputs:

• t: The Time to format
• buf: The backing buffer to use
• ampm: An optional pair of am/pm strings to use in place of the default

Returns:

• res: The formatted string, backed by buf

Example:

buf: [64]u8
now := time.now()
fmt.println(time.to_string_hms_12(now, buf[:]))
fmt.println(time.to_string_hms_12(now, buf[:], {"㏂", "㏘"}))

Formats a Time as a mm-dd-yy date string.

Inputs:

• t: The Time to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf.

Example:

buf: [MIN_YY_DATE_LEN]u8
now := time.now()
fmt.println(time.to_string_mm_dd_yy(now, buf[:]))

Formats a Time as a mm-dd-yyyy date string.

Inputs:

• t: The Time to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf.

Example:

buf: [MIN_YYYY_DATE_LEN]u8
now := time.now()
fmt.println(time.to_string_mm_dd_yyyy(now, buf[:]))

Formats a Time as a yy-mm-dd date string.

Inputs:

• t: The Time to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf.

Example:

buf: [MIN_YY_DATE_LEN]u8
now := time.now()
fmt.println(time.to_string_yy_mm_dd(now, buf[:]))

Formats a Time as a yyyy-mm-dd date string.

Inputs:

• t: The Time to format.
• buf: The backing buffer to use.

Returns:

• res: The formatted string, backed by buf.

Example:

buf: [MIN_YYYY_DATE_LEN]u8
now := time.now()
fmt.println(time.to_string_yyyy_mm_dd(now, buf[:]))

Alias for time_to_unix_nano.

Alias for time_to_unix.

Obtain the CPU's TSC frequency, in hertz.

This procedure tries to obtain the CPU's TSC frequency in hertz. If the CPU doesn't have an invariant TSC, this procedure returns with an error. Otherwise an attempt is made to fetch the TSC frequency from the OS. If this fails, the frequency is obtained by sleeping for the specified amount of time and dividing the readings from TSC by the duration of the sleep.

The duration of sleep can be controlled by fallback_sleep parameter.

Obtain time from unix seconds and unix nanoseconds.

Obtain the week day of the date specified by time.

Obtain the year of the date specified by time.

Obtain the time components from a time, a duration or a stopwatch's total.

Convert datetime components into time.

Obtain the time components from a time, a duration or a stopwatch's total, including nanoseconds.