Module time stdlib

time
Version:
0.3.3
License:
MIT
Dependencies from vmod:
0
Imports:
1
Imported by:
46
Repository:
OS-specific
Show selected OS-specific symbols.
Backend-specific
Show selected Backend-specific symbols.

Dependencies defined in v.mod

This section is empty.

Imports

Overview

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
    microsecond: 123456
    unix: 332198622
}

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()

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

Aliases

#type Duration

type Duration = i64

A lot of these are taken from the Go library.

#fn (Duration) nanoseconds

fn (d Duration) nanoseconds() i64

nanoseconds returns the duration as an integer number of nanoseconds.

#fn (Duration) microseconds

fn (d Duration) microseconds() i64

microseconds returns the duration as an integer number of microseconds.

#fn (Duration) milliseconds

fn (d Duration) milliseconds() i64

milliseconds returns the duration as an integer number of milliseconds.

#fn (Duration) seconds

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 (Duration) minutes

fn (d Duration) minutes() f64

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

#fn (Duration) hours

fn (d Duration) hours() f64

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

#fn (Duration) str

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 (Duration) timespec

Linux
fn (d Duration) timespec() C.timespec

return absolute timespec for now()+d

#fn (Duration) sys_milliseconds

Linux
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"

Constants

#constant days_string

days_string        = 'MonTueWedThuFriSatSun'

#constant long_days

long_days          = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday',
	'Sunday']

#constant month_days

month_days         = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]

#constant months_string

months_string      = 'JanFebMarAprMayJunJulAugSepOctNovDec'

#constant long_months

long_months        = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August',
	'September', 'October', 'November', 'December']

#constant absolute_zero_year

absolute_zero_year = i64(-292277022399)

#constant seconds_per_minute

seconds_per_minute = 60

#constant seconds_per_hour

seconds_per_hour   = 60 * seconds_per_minute

#constant seconds_per_day

seconds_per_day    = 24 * seconds_per_hour

#constant seconds_per_week

seconds_per_week   = 7 * seconds_per_day

#constant days_per_400_years

days_per_400_years = days_in_year * 400 + 97

#constant days_per_100_years

days_per_100_years = days_in_year * 100 + 24

#constant days_per_4_years

days_per_4_years   = days_in_year * 4 + 1

#constant days_in_year

days_in_year       = 365

#constant days_before

days_before        = [
	0,
	31,
	31 + 28,
	31 + 28 + 31,
	31 + 28 + 31 + 30,
	31 + 28 + 31 + 30 + 31,
	31 + 28 + 31 + 30 + 31 + 30,
	31 + 28 + 31 + 30 + 31 + 30 + 31,
	31 + 28 + 31 + 30 + 31 + 30 + 31 + 31,
	31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30,
	31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31,
	31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30,
	31 + 28 + 31 + 30 + 31 + 30 + 31 + 31 + 30 + 31 + 30 + 31,
]

#constant nanosecond

nanosecond  = Duration(1)

#constant microsecond

microsecond = Duration(1000 * nanosecond)

#constant millisecond

millisecond = Duration(1000 * microsecond)

#constant second

second      = Duration(1000 * millisecond)

#constant minute

minute      = Duration(60 * second)

#constant hour

hour        = Duration(60 * minute)

#constant infinite

infinite    = Duration(i64(9223372036854775807))

Sum types

This section is empty.

Functions

#fn darwin_now

Windows
fn darwin_now() Time

dummy to compile with all compilers

#fn darwin_now

Solaris
fn darwin_now() Time

dummy to compile with all compilers

#fn darwin_now

Linux
fn darwin_now() Time

darwin_now - dummy fn to compile on all platforms/compilers

#fn darwin_utc

Windows
fn darwin_utc() Time

dummy to compile with all compilers

#fn darwin_utc

Solaris
fn darwin_utc() Time

dummy to compile with all compilers

#fn darwin_utc

Linux
fn darwin_utc() Time

darwin_utc - dummy fn to compile on all platforms/compilers

#fn date_from_days_after_unix_epoch

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

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_civil

deprecated:use time.days_from_unix_epoch insteaddeprecated_after:2022-11-23
fn days_from_civil(year int, month int, day int) int

days_from_civil - return the number of days since the Unix epoch 1970-01-01.

deprecated: use time.days_from_unix_epoch instead

#fn days_from_unix_epoch

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

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

fn is_leap_year(year int) bool

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

#fn linux_now

Windows
fn linux_now() Time

dummy to compile with all compilers

#fn linux_utc

Windows
fn linux_utc() Time

dummy to compile with all compilers

#fn new_stopwatch

fn new_stopwatch(opts StopWatchOptions) StopWatch

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

#fn now

JavaScript
fn now() Time

#fn now

fn now() Time

now returns current local time.

#fn offset

fn offset() int

offset returns time zone UTC offset in seconds.

#fn parse

JavaScript
fn parse(s string) Time

parse returns time from a date string.

TODO(playX): JS Date expects iso8061 format of strings and other formats are implementation dependent, we probably want to implement parsing in JS.

#fn parse

fn parse(s string) !Time

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

#fn parse_iso8601

JavaScript
fn parse_iso8601(s string) !Time

#fn parse_iso8601

fn parse_iso8601(s string) !Time

parse_iso8601 parses rfc8601 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 and can be both +/- HH:mm remarks: not all iso8601 is supported also checks and support for leapseconds should be added in future PR

#fn parse_rfc2822

fn parse_rfc2822(s string) !Time

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

#fn parse_rfc3339

fn parse_rfc3339(s string) !Time

parse_rfc3339 returns 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

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

fn since(t Time) Duration

since returns the time duration elapsed since a given time.

#fn sleep

Windows
fn sleep(duration Duration)

sleep makes the calling thread sleep for a given duration (in nanoseconds).

#fn sleep

Linux
fn sleep(duration Duration)

sleep makes the calling thread sleep for a given duration (in nanoseconds).

#fn sleep

JavaScript
fn sleep(dur Duration)

#fn solaris_now

Windows
fn solaris_now() Time

dummy to compile with all compilers

#fn solaris_now

Linux
fn solaris_now() Time

solaris_now - dummy fn to compile on all platforms/compilers

#fn solaris_now

fn solaris_now() Time

dummy to compile with all compilers

#fn solaris_utc

Windows
fn solaris_utc() Time

dummy to compile with all compilers

#fn solaris_utc

Linux
fn solaris_utc() Time

solaris_utc - dummy fn to compile on all platforms/compilers

#fn solaris_utc

fn solaris_utc() Time

dummy to compile with all compilers

#fn sys_mono_now

Windows
fn sys_mono_now() u64

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

#fn sys_mono_now

Linux
fn sys_mono_now() u64

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

#fn sys_mono_now

JavaScript
fn sys_mono_now() u64

#fn ticks

JavaScript
fn ticks() i64

#fn ticks

fn ticks() i64

ticks returns a number of milliseconds elapsed since system start.

#fn unix

fn unix(abs i64) Time

unix returns a time struct from Unix time.

#fn unix2

fn unix2(abs i64, microsecond int) Time

unix2 returns a time struct from Unix time and microsecond value

#fn utc

JavaScript
fn utc() Time

#fn utc

fn utc() Time

utc returns the current UTC time.

#fn win_now

Linux
fn win_now() Time

dummy to compile with all compilers

#fn win_utc

Linux
fn win_utc() Time

dummy to compile with all compilers

#fn zero_timespec

Linux
fn zero_timespec() C.timespec

return timespec of 1970/1/1

Structs

#struct TimeParseError

pub struct TimeParseError {
	Error
	code int
}

TimeParseError represents a time parsing error.

fn (err TimeParseError) msg() string

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

#struct StopWatchOptions

params
pub struct StopWatchOptions {
	auto_start bool = true
}

#struct StopWatch

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

StopWatch is used to measure elapsed time.

#fn (&StopWatch) start

fn (mut t &StopWatch) start()

start starts the stopwatch. If the timer was paused, restarts counting.

#fn (&StopWatch) restart

fn (mut t &StopWatch) restart()

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

#fn (&StopWatch) stop

fn (mut t &StopWatch) stop()

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

#fn (&StopWatch) pause

fn (mut t &StopWatch) pause()

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

#fn (StopWatch) elapsed

fn (t StopWatch) elapsed() Duration

elapsed returns the Duration since the last start call

#struct C.timeval

pub struct C.timeval {
	tv_sec  u64
	tv_usec u64
}

C.timeval represents a C time value.

#struct Time

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

Time contains various time units for a point in time.

#fn new_time

fn new_time(t Time) Time

new_time returns a time struct with calculated Unix time.

#fn (Time) days_from_unix_epoch

inline
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 (Time) format

fn (t Time) format() string

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

#fn (Time) format_ss

fn (t Time) format_ss() string

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

#fn (Time) format_ss_milli

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 (Time) format_rfc3339

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 (Time) format_ss_micro

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 (Time) hhmm

fn (t Time) hhmm() string

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

#fn (Time) hhmmss

fn (t Time) hhmmss() string

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

#fn (Time) hhmm12

fn (t Time) hhmm12() string

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

#fn (Time) ymmdd

fn (t Time) ymmdd() string

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

#fn (Time) ddmmy

fn (t Time) ddmmy() string

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

#fn (Time) md

fn (t Time) md() string

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

#fn (Time) custom_format

fn (t Time) custom_format(s string) string

custom_format returns a date with custom format

Token Output
Month M 1 2 ... 11 12
Mo 1st 2nd ... 11th 12th
MM 01 02 ... 11 12
MMM Jan Feb ... Nov Dec
MMMM January February ... November December
Quarter Q 1 2 3 4
QQ 01 02 03 04
Qo 1st 2nd 3rd 4th
Day of Month D 1 2 ... 30 31
Do 1st 2nd ... 30th 31st
DD 01 02 ... 30 31
Day of Year DDD 1 2 ... 364 365
DDDo 1st 2nd ... 364th 365th
DDDD 001 002 ... 364 365
Day of Week d 0 1 ... 5 6 (Sun-Sat)
c 1 2 ... 6 7 (Mon-Sun)
dd Su Mo ... Fr Sa
ddd Sun Mon ... Fri Sat
dddd Sunday Monday ... Friday Saturday
Week of Year w 1 2 ... 52 53
wo 1st 2nd ... 52nd 53rd
ww 01 02 ... 52 53
Year YY 70 71 ... 29 30
YYYY 1970 1971 ... 2029 2030
Era N BC AD
NN Before Christ, Anno Domini
AM/PM A AM PM
a am pm
Hour H 0 1 ... 22 23
HH 00 01 ... 22 23
h 1 2 ... 11 12
hh 01 02 ... 11 12
k 1 2 ... 23 24
kk 01 02 ... 23 24
Minute m 0 1 ... 58 59
mm 00 01 ... 58 59
Second s 0 1 ... 58 59
ss 00 01 ... 58 59
Offset Z -7 -6 ... +5 +6
ZZ -0700 -0600 ... +0500 +0600
ZZZ -07:00 -06:00 ... +05:00 +06:00

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 (Time) clean

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 (Time) clean12

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 (Time) get_fmt_time_str

fn (t Time) get_fmt_time_str(fmt_time FormatTime) string

get_fmt_time_str returns a date string with specified FormatTime type.

#fn (Time) get_fmt_date_str

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 (Time) get_fmt_str

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 (Time) utc_string

fn (t Time) utc_string() string

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

#fn (Time) operator==

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

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

#fn (Time) operator<

inline
fn (t1 Time) < (t2 Time) bool

operator < returns true if provided time is less than time

#fn (Time) operator-

inline
fn (lhs Time) - (rhs Time) Duration

Time subtract using operator overloading.

#fn (Time) str

fn (t Time) str() string

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

#fn (Time) strftime

fn (t Time) strftime(fmt string) string

strftime returns the formatted time using strftime(3)

#fn (Time) local

JavaScript
fn (t Time) local() Time

/ Returns local time

#fn (&Time) smonth

fn (t &Time) smonth() string

smonth returns month name abbreviation.

#fn (&Time) unix_time

inline
fn (t &Time) unix_time() i64

unix_time returns Unix time.

#fn (&Time) unix_time_milli

inline
fn (t &Time) unix_time_milli() i64

unix_time_milli returns Unix time with millisecond resolution.

#fn (&Time) add

fn (t &Time) add(d Duration) Time

add returns a new time that duration is added

#fn (&Time) add_seconds

fn (t &Time) add_seconds(seconds int) Time

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

#fn (&Time) add_days

fn (t &Time) add_days(days int) Time

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

#fn (&Time) relative

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 (&Time) relative_short

fn (t &Time) relative_short() string

relative_short returns a string saying how long ago a time occured 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 (&Time) day_of_week

fn (t &Time) day_of_week() int

day_of_week returns the current day as an integer.

#fn (&Time) weekday_str

fn (t &Time) weekday_str() string

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

#fn (&Time) long_weekday_str

fn (t &Time) long_weekday_str() string

long_weekday_str returns the current day as a string.

#fn (&Time) debug

fn (t &Time) debug() string

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

#fn (&Time) local_to_utc

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 (&Time) utc_to_local

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 (&Time) as_local

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 (&Time) as_utc

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 (&Time) is_utc

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 .

#struct C.timeval

pub struct C.timeval {
	tv_sec  u64
	tv_usec u64
}

#struct C.timeval

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

dummy to compile with all compilers

#struct C._FILETIME

Windows
pub struct C._FILETIME {
	dwLowDateTime  u32
	dwHighDateTime u32
}

#struct C.timeval

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

dummy to compile with all compilers

Interfaces

This section is empty.

Enums

#enum FormatTime

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

FormatDelimiter contains different time formats.

#enum FormatDate

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

FormatDelimiter contains different date formats.

#enum FormatDelimiter

pub enum FormatDelimiter {
	dot
	hyphen
	slash
	space
	no_delimiter
}

FormatDelimiter contains different time/date delimiters.