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
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')
}
Constants #
const (
days_string = 'MonTueWedThuFriSatSun'
long_days = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday',
'Sunday']
month_days = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
months_string = 'JanFebMarAprMayJunJulAugSepOctNovDec'
long_months = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August',
'September', 'October', 'November', 'December']
// The unsigned zero year for internal calculations.
// Must be 1 mod 400, and times before it will not compute correctly,
// but otherwise can be changed at will.
absolute_zero_year = i64(-292277022399)
seconds_per_minute = 60
seconds_per_hour = 60 * seconds_per_minute
seconds_per_day = 24 * seconds_per_hour
seconds_per_week = 7 * seconds_per_day
days_per_400_years = days_in_year * 400 + 97
days_per_100_years = days_in_year * 100 + 24
days_per_4_years = days_in_year * 4 + 1
days_in_year = 365
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,
]
)
const (
nanosecond = Duration(1)
microsecond = Duration(1000 * nanosecond)
millisecond = Duration(1000 * microsecond)
second = Duration(1000 * millisecond)
minute = Duration(60 * second)
hour = Duration(60 * minute)
infinite = Duration(i64(9223372036854775807))
)
fn darwin_now #
fn darwin_now() Time
darwin_now - dummy fn to compile on all platforms/compilers
fn darwin_utc #
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 #
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 new_stopwatch #
fn new_stopwatch(opts StopWatchOptions) StopWatch
new_stopwatch initializes a new StopWatch with the current time as start.
fn new_time #
fn new_time(t Time) Time
new_time returns a time struct with calculated Unix 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 #
fn parse(s string) !Time
parse returns time from a date string in "YYYY-MM-DD HH:mm:ss" format.
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 #
fn sleep(duration Duration)
sleep makes the calling thread sleep for a given duration (in nanoseconds).
fn solaris_now #
fn solaris_now() Time
solaris_now - dummy fn to compile on all platforms/compilers
fn solaris_utc #
fn solaris_utc() Time
solaris_utc - dummy fn to compile on all platforms/compilers
fn sys_mono_now #
fn sys_mono_now() u64
sys_mono_now returns a monotonically increasing time, NOT a time adjusted for daylight savings, location etc.
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 #
fn utc() Time
utc returns the current UTC time.
fn win_now #
fn win_now() Time
dummy to compile with all compilers
fn win_utc #
fn win_utc() Time
dummy to compile with all compilers
fn zero_timespec #
fn zero_timespec() C.timespec
return timespec of 1970/1/1
type Duration #
type Duration = i64
A lot of these are taken from the Go library.
fn (Duration) hours #
fn (d Duration) hours() f64
hours returns the duration as a floating point number of hours.
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) minutes #
fn (d Duration) minutes() f64
minutes returns the duration as a floating point number of minutes.
fn (Duration) nanoseconds #
fn (d Duration) nanoseconds() i64
nanoseconds returns the duration as an integer number of nanoseconds.
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) 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) sys_milliseconds #
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 (Duration) timespec #
fn (d Duration) timespec() C.timespec
return absolute timespec for now()+d
enum FormatDate #
enum FormatDate {
ddmmyy
ddmmyyyy
mmddyy
mmddyyyy
mmmd
mmmdd
mmmddyy
mmmddyyyy
no_date
yyyymmdd
yymmdd
}
FormatDelimiter contains different date formats.
enum FormatDelimiter #
enum FormatDelimiter {
dot
hyphen
slash
space
no_delimiter
}
FormatDelimiter contains different time/date delimiters.
enum FormatTime #
enum FormatTime {
hhmm12
hhmm24
hhmmss12
hhmmss24
hhmmss24_milli
hhmmss24_micro
no_time
}
FormatDelimiter contains different time formats.
struct C.timeval #
struct C.timeval {
tv_sec u64
tv_usec u64
}
C.timeval represents a C time value.
struct StopWatch #
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 StopWatchOptions #
struct StopWatchOptions {
auto_start bool = true
}
struct Time #
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 (Time) - #
fn (lhs Time) - (rhs Time) Duration
Time subtract using operator overloading.
fn (Time) < #
fn (t1 Time) < (t2 Time) bool
operator <
returns true if provided time is less than time
fn (Time) == #
fn (t1 Time) == (t2 Time) bool
operator ==
returns true if provided time is equal to time
fn (Time) add #
fn (t Time) add(d Duration) Time
add returns a new time that duration is added
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) 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) 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) 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) 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 |
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) day_of_week #
fn (t Time) day_of_week() int
day_of_week returns the current day as an integer.
fn (Time) days_from_unix_epoch #
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) ddmmy #
fn (t Time) ddmmy() string
ddmmy returns a date string in "DD.MM.YYYY" format.
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) format #
fn (t Time) format() string
format returns a date string in "YYYY-MM-DD HH:mm" 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 #
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_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) 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) 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) 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) hhmm #
fn (t Time) hhmm() string
hhmm returns a date string in "HH:mm" format (24h).
fn (Time) hhmm12 #
fn (t Time) hhmm12() string
hhmm12 returns a date string in "hh:mm" format (12h).
fn (Time) hhmmss #
fn (t Time) hhmmss() string
hhmmss returns a date string in "HH:mm:ss" format (24h).
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 .
fn (Time) local #
fn (t Time) local() Time
local returns t with the location set to local time.
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) long_weekday_str #
fn (t Time) long_weekday_str() string
long_weekday_str returns the current day as a string.
fn (Time) md #
fn (t Time) md() string
md returns a date string in "MMM D" format.
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) smonth #
fn (t Time) smonth() string
smonth returns month name abbreviation.
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) unix_time #
fn (t Time) unix_time() i64
unix_time returns Unix time.
fn (Time) unix_time_milli #
fn (t Time) unix_time_milli() i64
unix_time_milli returns Unix time with millisecond resolution.
fn (Time) utc_string #
fn (t Time) utc_string() string
This is just a TEMPORARY function for cookies and their expire dates
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) weekday_str #
fn (t Time) weekday_str() string
weekday_str returns the current day as a string 3 letter abbreviation.
fn (Time) year_day #
fn (t Time) year_day() int
year_day returns the current day of the year as an integer.
See also #Time.custom_format .
fn (Time) ymmdd #
fn (t Time) ymmdd() string
ymmdd returns a date string in "YYYY-MM-DD" format.
struct TimeParseError #
struct TimeParseError {
Error
code int
}
TimeParseError represents a time parsing error.
fn (TimeParseError) msg #
fn (err TimeParseError) msg() string
msg implements the IError.msg()
method for TimeParseError
.
- README
- Constants
- fn darwin_now
- fn darwin_utc
- fn date_from_days_after_unix_epoch
- fn day_of_week
- fn days_from_civil
- fn days_from_unix_epoch
- fn days_in_month
- fn is_leap_year
- fn new_stopwatch
- fn new_time
- fn now
- fn offset
- fn parse
- fn parse_iso8601
- fn parse_rfc2822
- fn parse_rfc3339
- fn portable_timegm
- fn since
- fn sleep
- fn solaris_now
- fn solaris_utc
- fn sys_mono_now
- fn ticks
- fn unix
- fn unix2
- fn utc
- fn win_now
- fn win_utc
- fn zero_timespec
- type Duration
- enum FormatDate
- enum FormatDelimiter
- enum FormatTime
- struct C.timeval
- struct StopWatch
- struct StopWatchOptions
- struct Time
- fn -
- fn <
- fn ==
- fn add
- fn add_days
- fn add_seconds
- fn as_local
- fn as_utc
- fn clean
- fn clean12
- fn custom_format
- fn day_of_week
- fn days_from_unix_epoch
- fn ddmmy
- fn debug
- fn format
- fn format_rfc3339
- fn format_ss
- fn format_ss_micro
- fn format_ss_milli
- fn get_fmt_date_str
- fn get_fmt_str
- fn get_fmt_time_str
- fn hhmm
- fn hhmm12
- fn hhmmss
- fn is_utc
- fn local
- fn local_to_utc
- fn long_weekday_str
- fn md
- fn relative
- fn relative_short
- fn smonth
- fn str
- fn strftime
- fn unix_time
- fn unix_time_milli
- fn utc_string
- fn utc_to_local
- fn weekday_str
- fn year_day
- fn ymmdd
- struct TimeParseError