time #

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

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')
}

fn date_from_days_after_unix_epoch(days int) Time

date_from_days_after_unix_epoch - convert number of days after the unix epoch 1970-01-01, to a Time. Only the year, month and day of the returned Time will be set, everything else will be 0.

fn day_of_week(y int, m int, d int) int

day_of_week returns the current day of a given year, month, and day, as an integer.

fn days_from_unix_epoch(year int, month int, day int) int

days_from_unix_epoch - return the number of days since the Unix epoch 1970-01-01. A detailed description of the algorithm here is in: http://howardhinnant.github.io/date_algorithms.html Note that function will return negative values for days before 1970-01-01.

fn days_in_month(month int, year int) !int

days_in_month returns a number of days in a given month.

fn is_leap_year(year int) bool

is_leap_year checks if a given a year is a leap year.

fn new(t Time) Time

new returns a time struct with the calculated Unix time.

fn new_stopwatch(opts StopWatchOptions) StopWatch

new_stopwatch initializes a new StopWatch with the current time as start.

fn new_time(t Time) Time

new_time returns a time struct with the calculated Unix time.

fn now() Time

now returns the current local time.

fn offset() int

offset returns time zone UTC offset in seconds.

fn parse(s string) !Time

parse returns the time from a date string in "YYYY-MM-DD HH:mm:ss" format.

fn parse_format(s string, format string) !Time

parse_format parses the string s, as a custom format, containing the following specifiers:

fn parse_iso8601(s string) !Time

parse_iso8601 parses the ISO 8601 time format yyyy-MM-ddTHH:mm:ss.dddddd+dd:dd as local time. The fraction part is difference in milli seconds, and the last part is offset from UTC time. Both can be +/- HH:mm . See https://en.wikipedia.org/wiki/ISO_8601 . Remarks: not all of ISO 8601 is supported; checks and support for leapseconds should be added.

fn parse_rfc2822(s string) !Time

parse_rfc2822 returns the time from a date string in RFC 2822 datetime format.

fn parse_rfc3339(s string) !Time

parse_rfc3339 returns the time from a date string in RFC 3339 datetime format. See also https://ijmacd.github.io/rfc3339-iso8601/ for a visual reference of the differences between ISO-8601 and RFC 3339.

fn portable_timegm(t &C.tm) i64

portable_timegm does the same as C._mkgmtime, but unlike it, can work with dates before the Unix epoch of 1970-01-01 .

fn since(t Time) Duration

since returns the time duration elapsed since a given time.

fn sleep(duration Duration)

sleep suspends the execution of the calling thread for a given duration (in nanoseconds).

fn sys_mono_now() u64

sys_mono_now returns a monotonically increasing time, NOT a time adjusted for daylight savings, location etc.

fn ticks() i64

ticks returns the number of milliseconds since the UNIX epoch. On Windows ticks returns the number of milliseconds elapsed since system start.

fn unix(epoch i64) Time

unix returns a Time calculated from the given Unix timestamp in seconds since 1970-01-01

fn unix_micro(us i64) Time

unix_micro returns a Time calculated from the given Unix timestamp in microseconds since 1970-01-01

fn unix_microsecond(epoch i64, microsecond int) Time

unix_microsecond returns a Time struct, given an Unix timestamp in seconds, and a microsecond value

fn unix_milli(ms i64) Time

unix_milli returns a Time calculated from the given Unix timestamp in milliseconds since 1970-01-01

fn unix_nano(ns i64) Time

unix_nano returns a Time calculated from the given Unix timestamp in nanoseconds since 1970-01-01

fn unix_nanosecond(abs_unix_timestamp i64, nanosecond int) Time

unix_nanosecond returns a Time struct given a Unix timestamp in seconds and a nanosecond value

fn utc() Time

utc returns the current UTC time.

fn Time.new(t Time) Time

type Duration = i64

A lot of these are taken from the Go library.

fn (d Duration) days() f64

days returns the duration as a floating point number of days.

fn (d Duration) debug() string

debug returns a detailed breakdown of the Duration, as: 'Duration: - 50days, 4h, 3m, 7s, 541ms, 78us, 9ns'

fn (d Duration) hours() f64

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

fn (d Duration) microseconds() i64

microseconds returns the duration as an integer number of microseconds.

fn (d Duration) milliseconds() i64

milliseconds returns the duration as an integer number of milliseconds.

fn (d Duration) minutes() f64

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

fn (d Duration) nanoseconds() i64

nanoseconds returns the duration as an integer number of nanoseconds.

fn (d Duration) seconds() f64

The following functions return floating point numbers because it's common to consider all of them in sub-one intervals seconds returns the duration as a floating point number of seconds.

fn (d Duration) str() string

str pretty prints the duration

h:m:s      // 5:02:33
m:s.mi<s>  // 2:33.015
s.mi<s>    // 33.015s
mi.mc<ms>  // 15.007ms
mc.ns<ns>  // 7.234us
ns<ns>     // 234ns

fn (d Duration) sys_milliseconds() int

some *nix system functions (e.g. C.poll(), C.epoll_wait()) accept an int value as timeout in milliseconds with the special value -1 meaning "infinite"

fn (d Duration) timespec() C.timespec

return absolute timespec for now()+d

enum FormatDate {
	ddmmyy
	ddmmyyyy
	mmddyy
	mmddyyyy
	mmmd
	mmmdd
	mmmddyy
	mmmddyyyy
	no_date
	yyyymmdd
	yymmdd
}

FormatDelimiter contains different date formats.

enum FormatDelimiter {
	dot
	hyphen
	slash
	space
	no_delimiter
}

FormatDelimiter contains different time/date delimiters.

enum FormatTime {
	hhmm12
	hhmm24
	hhmmss12
	hhmmss24
	hhmmss24_milli
	hhmmss24_micro
	hhmmss24_nano
	no_time
}

FormatDelimiter contains different time formats.

struct C.timespec {
pub mut:
	tv_sec  i64
	tv_nsec i64
}

in most systems, these are __quad_t, which is an i64

struct C.timeval {
pub:
	tv_sec  u64
	tv_usec u64
}

C.timeval represents a C time value.

struct C.tm {
pub mut:
	tm_sec    int
	tm_min    int
	tm_hour   int
	tm_mday   int
	tm_mon    int
	tm_year   int
	tm_wday   int
	tm_yday   int
	tm_isdst  int
	tm_gmtoff int
}

struct StopWatch {
mut:
	elapsed u64
pub mut:
	start u64
	end   u64
}

StopWatch is used to measure elapsed time.

fn (mut t StopWatch) start()

start starts the stopwatch. If the timer was paused, it continues counting.

fn (mut t StopWatch) restart()

restart restarts the stopwatch. If the timer was paused, it restarts counting.

fn (mut t StopWatch) stop()

stop stops the timer, by setting the end time to the current time.

fn (mut t StopWatch) pause()

pause resets the start time and adds the current elapsed time to elapsed.

fn (t StopWatch) elapsed() Duration

elapsed returns the Duration since the last start call

struct StopWatchOptions {
pub:
	auto_start bool = true
}

struct Time {
	unix i64
pub:
	year       int
	month      int
	day        int
	hour       int
	minute     int
	second     int
	nanosecond int
	is_local   bool // used to make time.now().local().local() == time.now().local()
}

Time contains various time units for a point in time.

fn (lhs Time) - (rhs Time) Duration

Time subtract using operator overloading.

fn (t1 Time) < (t2 Time) bool

operator < returns true if provided time is less than time

fn (t1 Time) == (t2 Time) bool

operator == returns true if provided time is equal to time

fn (t Time) add(duration_in_nanosecond Duration) Time

add returns a new time with the given duration added.

fn (t Time) add_days(days int) Time

add_days returns a new time struct with an added number of days.

fn (t Time) add_seconds(seconds int) Time

add_seconds returns a new time struct with an added number of seconds.

fn (t Time) as_local() Time

as_local returns the exact same time, as the receiver t, but with its .is_local field set to true. See also #Time.utc_to_local .

fn (t Time) as_utc() Time

as_utc returns the exact same time, as the receiver t, but with its .is_local field set to false. See also #Time.local_to_utc .

fn (t Time) clean() string

clean returns a date string in a following format:- a date string in "HH:mm" format (24h) for current day

• a date string in "MMM D HH:mm" format (24h) for date of current year
• a date string formatted with format function for other dates

fn (t Time) clean12() string

clean12 returns a date string in a following format:- a date string in "hh:mm" format (12h) for current day

• a date string in "MMM D hh:mm" format (12h) for date of current year
• a date string formatted with format function for other dates

fn (t Time) custom_format(s string) string

custom_format returns a date with custom format

Usage:

println(time.now().custom_format('MMMM Mo YY N kk:mm:ss A')) // output like: January 1st 22 AD 13:45:33 PM

fn (t Time) day_of_week() int

day_of_week returns the current day as an integer.

fn (t Time) days_from_unix_epoch() int

days_from_unix_epoch - return the number of days since the Unix epoch 1970-01-01. A detailed description of the algorithm here is in: http://howardhinnant.github.io/date_algorithms.html Note that method will return negative values for days before 1970-01-01.

fn (t Time) ddmmy() string

ddmmy returns a date string in "DD.MM.YYYY" format.

fn (t Time) debug() string

debug returns detailed breakdown of time (Time{ year: YYYY month: MM day: dd hour: HH: minute: mm second: ss nanosecond: nanos unix: unix })

fn (t Time) format() string

format returns a date string in "YYYY-MM-DD HH:mm" format (24h).

fn (t Time) format_rfc3339() string

format_rfc3339 returns a date string in "YYYY-MM-DDTHH:mm:ss.123Z" format (24 hours, see https://www.rfc-editor.org/rfc/rfc3339.html) RFC3339 is an Internet profile, based on the ISO 8601 standard for for representation of dates and times using the Gregorian calendar. It is intended to improve consistency and interoperability, when representing and using date and time in Internet protocols.

fn (t Time) format_rfc3339_micro() string

format_rfc3339_micro returns a date string in "YYYY-MM-DDTHH:mm:ss.123456Z" format (24 hours, see https://www.rfc-editor.org/rfc/rfc3339.html)

fn (t Time) format_rfc3339_nano() string

format_rfc3339_nano returns a date string in "YYYY-MM-DDTHH:mm:ss.123456789Z" format (24 hours, see https://www.rfc-editor.org/rfc/rfc3339.html)

fn (t Time) format_ss() string

format_ss returns a date string in "YYYY-MM-DD HH:mm:ss" format (24h).

fn (t Time) format_ss_micro() string

format_ss_micro returns a date string in "YYYY-MM-DD HH:mm:ss.123456" format (24h).

fn (t Time) format_ss_milli() string

format_ss_milli returns a date string in "YYYY-MM-DD HH:mm:ss.123" format (24h).

fn (t Time) format_ss_nano() string

format_ss_nano returns a date string in "YYYY-MM-DD HH:mm:ss.123456789" format (24h).

fn (t Time) get_fmt_date_str(fmt_dlmtr FormatDelimiter, fmt_date FormatDate) string

get_fmt_time_str returns a date string with specified FormatDelimiter and FormatDate type.

fn (t Time) get_fmt_str(fmt_dlmtr FormatDelimiter, fmt_time FormatTime, fmt_date FormatDate) string

get_fmt_str returns a date string with specified FormatDelimiter, FormatTime type, and FormatDate type.

fn (t Time) get_fmt_time_str(fmt_time FormatTime) string

get_fmt_time_str returns a date string with specified FormatTime type.

fn (t Time) hhmm() string

hhmm returns a date string in "HH:mm" format (24h).

fn (t Time) hhmm12() string

hhmm12 returns a date string in "hh:mm" format (12h).

fn (t Time) hhmmss() string

hhmmss returns a date string in "HH:mm:ss" format (24h).

fn (t Time) http_header_string() string

http_header_string returns a date string in the format used in HTTP headers, as defined in RFC 2616. e.g. "Sun, 06 Nov 1994 08:49:37 GMT"

fn (t Time) is_utc() bool

is_utc returns true, when the receiver t is a UTC time, and false otherwise. See also #Time.utc_to_local .

fn (t Time) local() Time

local returns t with the location set to local time.

fn (t Time) local_to_utc() Time

local_to_utc converts the receiver t to the corresponding UTC time, if it contains local time. If the receiver already does contain UTC time, it returns it unchanged.

fn (t Time) long_weekday_str() string

long_weekday_str returns the current day as a string.

fn (t Time) md() string

md returns a date string in "MMM D" format.

fn (t Time) relative() string

relative returns a string representation of the difference between t and the current time.

Sample outputs:

// future
now
in 5 minutes
in 1 day
on Feb 17
// past
2 hours ago
last Jan 15
5 years ago

fn (t Time) relative_short() string

relative_short returns a string saying how long ago a time occurred as follows: 0-30 seconds: "now"; 30-60 seconds: "1m"; anything else is rounded to the nearest minute, hour, day, or year

Sample outputs:

// future
now
in 5m
in 1d
// past
2h ago
5y ago

fn (t Time) smonth() string

smonth returns the month name abbreviation.

fn (t Time) str() string

str returns the time in the same format as parse expects ("YYYY-MM-DD HH:mm:ss").

fn (t Time) strftime(fmt string) string

strftime returns the formatted time using strftime(3)

fn (t Time) unix() i64

unix returns the UNIX time with second resolution.

fn (t Time) unix_micro() i64

unix_micro returns the UNIX time with microsecond resolution.

fn (t Time) unix_milli() i64

unix_milli returns the UNIX time with millisecond resolution.

fn (t Time) unix_nano() i64

unix_nano returns the UNIX time with nanosecond resolution.

fn (t Time) unix_time() i64

unix_time returns the UNIX time with second resolution.

fn (t Time) unix_time_micro() i64

unix_time_micro returns the UNIX time with microsecond resolution.

fn (t Time) unix_time_milli() i64

unix_time_milli returns the UNIX time with millisecond resolution.

fn (t Time) unix_time_nano() i64

unix_time_nano returns the UNIX time with nanosecond resolution.

fn (t Time) utc_string() string

This is just a TEMPORARY function for cookies and their expire dates

fn (u Time) utc_to_local() Time

utc_to_local converts the receiver u to the corresponding local time, if it contains UTC time. If the receiver already does contain local time, it returns it unchanged.

fn (t Time) weekday_str() string

weekday_str returns the current day as a string 3 letter abbreviation.

fn (t Time) year_day() int

year_day returns the current day of the year as an integer. See also #Time.custom_format .

fn (t Time) ymmdd() string

ymmdd returns a date string in "YYYY-MM-DD" format.

struct TimeParseError {
	Error
	code    int
	message string
}

TimeParseError represents a time parsing error.

fn (err TimeParseError) msg() string

msg implements the IError.msg() method for TimeParseError.