agila_open_tool/tools/v/vlib/time/README.md

Description

V's time module, provides utilities for working with time and dates:

• parsing of time values expressed in one of the commonly used standard time/date formats
• formatting of time values
• arithmetic over times/durations
• converting between local time and UTC (timezone support)
• stop watches for accurately measuring time durations
• sleeping for a period of time

Examples

You can see the current time. See:

import time

println(time.now())

time.Time values can be compared, see:

import time

const time_to_test = time.Time{
	year:       1980
	month:      7
	day:        11
	hour:       21
	minute:     23
	second:     42
	nanosecond: 123456789
}

println(time_to_test.format())

assert '1980-07-11 21:23' == time_to_test.format()
assert '1980-07-11 21:23:42' == time_to_test.format_ss()
assert '1980-07-11 21:23:42.123' == time_to_test.format_ss_milli()
assert '1980-07-11 21:23:42.123456' == time_to_test.format_ss_micro()
assert '1980-07-11 21:23:42.123456789' == time_to_test.format_ss_nano()

You can also parse strings to produce time.Time values, see:

import time

s := '2018-01-27 12:48:34'
t := time.parse(s) or { panic('failing format: ${s} | err: ${err}') }
println(t)
println(t.unix())

V's time module also has these parse methods:

fn parse(s string) !Time
fn parse_iso8601(s string) !Time
fn parse_rfc2822(s string) !Time
fn parse_rfc3339(s string) !Time

time.new(...) validates the provided fields before calculating the Unix timestamp. Omitted month and day values default to 1, and out-of-range values panic. Use t.is_zero() to check whether a time.Time is still its zero value before formatting or serializing it.

Another very useful feature of the time module is the stop watch, for when you want to measure short time periods, elapsed while you executed other tasks. See:

import time

fn do_something() {
	time.sleep(510 * time.millisecond)
}

fn main() {
	sw := time.new_stopwatch()
	do_something()
	println('Note: do_something() took: ${sw.elapsed().milliseconds()} ms')
}