Skip to content

time #

Description:

time 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:

import time

println(time.now())

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 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(oy int, m int, d int) int

days_from_civil - 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 it 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) 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
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) day_of_week #

fn (t Time) day_of_week() int

day_of_week returns the current day as an integer.

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_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) local #

fn (t Time) local() Time

local returns t with the location set to local time.

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) weekday_str #

fn (t Time) weekday_str() string

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

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.