Module times

This module contains routines and types for dealing with time. This module is available for the JavaScript target.

Examples:

import times, os
var
  t = cpuTime()

sleep(100)   # replace this with something to be timed
echo "Time taken: ",cpuTime() - t

echo "My formatted time: ", format(getLocalTime(getTime()), "d MMMM yyyy HH:mm")
echo "Using predefined formats: ", getClockStr(), " ", getDateStr()

echo "epochTime() float value: ", epochTime()
echo "getTime()   float value: ", toSeconds(getTime())
echo "cpuTime()   float value: ", cpuTime()
echo "An hour from now      : ", getLocalTime(getTime()) + 1.hours
echo "An hour from (UTC) now: ", getGmTime(getTime()) + initInterval(0,0,0,1)

Types

Month = enum
  mJan, mFeb, mMar, mApr, mMay, mJun, mJul, mAug, mSep, mOct, mNov, mDec
represents a month   Source Edit
WeekDay = enum
  dMon, dTue, dWed, dThu, dFri, dSat, dSun
represents a weekday   Source Edit
Time = distinct TimeImpl
  Source Edit
TimeInfo = object of RootObj
  second*: range[0 .. 61]        ## The number of seconds after the minute,
                      ## normally in the range 0 to 59, but can
                      ## be up to 61 to allow for leap seconds.
  minute*: range[0 .. 59]        ## The number of minutes after the hour,
                      ## in the range 0 to 59.
  hour*: range[0 .. 23]          ## The number of hours past midnight,
                    ## in the range 0 to 23.
  monthday*: range[1 .. 31]      ## The day of the month, in the range 1 to 31.
  month*: Month                ## The current month.
  year*: int                   ## The current year.
  weekday*: WeekDay            ## The current day of the week.
  yearday*: range[0 .. 365]      ## The number of days since January 1,
                        ## in the range 0 to 365.
                        ## Always 0 if the target is JS.
  isDST*: bool                 ## Determines whether DST is in effect.
             ## Semantically, this adds another negative hour
             ## offset to the time in addition to the timezone.
  timezone*: int               ## The offset of the (non-DST) timezone in seconds
               ## west of UTC. Note that the sign of this number
               ## is the opposite of the one in a formatted
               ## timezone string like ``+01:00`` (which would be
               ## parsed into the timezone ``-3600``).
  
represents a time in different parts   Source Edit
TimeInterval = object
  milliseconds*: int           ## The number of milliseconds
  seconds*: int                ## The number of seconds
  minutes*: int                ## The number of minutes
  hours*: int                  ## The number of hours
  days*: int                   ## The number of days
  months*: int                 ## The number of months
  years*: int                  ## The number of years
  
a time interval   Source Edit

Procs

proc fromSeconds(since1970: int64): Time {.
tags: [], raises: [], gcsafe, locks: 0
.}
Takes an int which contains the number of seconds since the unix epoch and returns a time object.   Source Edit
proc `<`(a, b: Time): bool {.
gcsafe, extern: "ntLtTime", tags: [], raises: [], noSideEffect
.}
returns true iff a < b, that is iff a happened before b.   Source Edit
proc `<=`(a, b: Time): bool {.
gcsafe, extern: "ntLeTime", tags: [], raises: [], noSideEffect
.}
returns true iff a <= b.   Source Edit
proc `==`(a, b: Time): bool {.
gcsafe, extern: "ntEqTime", tags: [], raises: [], noSideEffect
.}
returns true if a == b, that is if both times represent the same value   Source Edit
proc initInterval(milliseconds, seconds, minutes, hours, days, months, years: int = 0): TimeInterval {.
raises: [], tags: []
.}

creates a new TimeInterval.

You can also use the convenience procedures called milliseconds, seconds, minutes, hours, days, months, and years.

Example:

let day = initInterval(hours=24)
let tomorrow = getTime() + day
echo(tomorrow)
  Source Edit
proc `+`(ti1, ti2: TimeInterval): TimeInterval {.
raises: [], tags: []
.}
Adds two TimeInterval objects together.   Source Edit
proc `-`(ti: TimeInterval): TimeInterval {.
raises: [], tags: []
.}
Reverses a time interval .. code-block:: nim

let day = -initInterval(hours=24) echo day # -> (milliseconds: 0, seconds: 0, minutes: 0, hours: 0, days: -1, months: 0, years: 0)

  Source Edit
proc `-`(ti1, ti2: TimeInterval): TimeInterval {.
raises: [], tags: []
.}

Subtracts TimeInterval ti1 from ti2.

Time components are compared one-by-one, see output:

let a = fromSeconds(1_000_000_000)
let b = fromSeconds(1_500_000_000)
echo b.toTimeInterval - a.toTimeInterval
# (milliseconds: 0, seconds: -40, minutes: -6, hours: 1, days: -2, months: -2, years: 16)
  Source Edit
proc isLeapYear(year: int): bool {.
raises: [], tags: []
.}
returns true if year is a leap year   Source Edit
proc getDaysInMonth(month: Month; year: int): int {.
raises: [], tags: []
.}
Get the number of days in a month of a year   Source Edit
proc getDaysInYear(year: int): int {.
raises: [], tags: []
.}
Get the number of days in a year   Source Edit
proc `+`(a: TimeInfo; interval: TimeInterval): TimeInfo {.
raises: [Exception], tags: [TimeEffect]
.}

adds interval time from TimeInfo a.

Note: This has been only briefly tested and it may not be very accurate.

  Source Edit
proc `-`(a: TimeInfo; interval: TimeInterval): TimeInfo {.
raises: [Exception], tags: [TimeEffect]
.}

subtracts interval time from TimeInfo a.

Note: This has been only briefly tested, it is inaccurate especially when you subtract so much that you reach the Julian calendar.

  Source Edit
proc miliseconds(t: TimeInterval): int {.
deprecated, raises: [], tags: []
.}
  Source Edit
proc miliseconds=(t: var TimeInterval; milliseconds: int) {.
deprecated, raises: [], tags: []
.}

An alias for a misspelled field in TimeInterval.

Warning: This should not be used! It will be removed in the next version.

  Source Edit
proc getDateStr(): string {.
gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [Exception]
.}
gets the current date as a string of the format YYYY-MM-DD.   Source Edit
proc getClockStr(): string {.
gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [Exception]
.}
gets the current clock time as a string of the format HH:MM:SS.   Source Edit
proc `$`(day: WeekDay): string {.
raises: [], tags: []
.}
stingify operator for WeekDay.   Source Edit
proc `$`(m: Month): string {.
raises: [], tags: []
.}
stingify operator for Month.   Source Edit
proc milliseconds(ms: int): TimeInterval {.
inline, raises: [], tags: []
.}

TimeInterval of ms milliseconds

Note: not all time functions have millisecond resolution

  Source Edit
proc seconds(s: int): TimeInterval {.
inline, raises: [], tags: []
.}

TimeInterval of s seconds

echo getTime() + 5.second

  Source Edit
proc minutes(m: int): TimeInterval {.
inline, raises: [], tags: []
.}

TimeInterval of m minutes

echo getTime() + 5.minutes

  Source Edit
proc hours(h: int): TimeInterval {.
inline, raises: [], tags: []
.}

TimeInterval of h hours

echo getTime() + 2.hours

  Source Edit
proc days(d: int): TimeInterval {.
inline, raises: [], tags: []
.}

TimeInterval of d days

echo getTime() + 2.days

  Source Edit
proc months(m: int): TimeInterval {.
inline, raises: [], tags: []
.}

TimeInterval of m months

echo getTime() + 2.months

  Source Edit
proc years(y: int): TimeInterval {.
inline, raises: [], tags: []
.}

TimeInterval of y years

echo getTime() + 2.years

  Source Edit
proc `+=`(t: var Time; ti: TimeInterval) {.
raises: [Exception], tags: [TimeEffect]
.}
modifies t by adding the interval ti   Source Edit
proc `+`(t: Time; ti: TimeInterval): Time {.
raises: [Exception], tags: [TimeEffect]
.}

adds the interval ti to Time t by converting to localTime, adding the interval, and converting back

echo getTime() + 1.day

  Source Edit
proc `-=`(t: var Time; ti: TimeInterval) {.
raises: [Exception], tags: [TimeEffect]
.}
modifies t by subtracting the interval ti   Source Edit
proc `-`(t: Time; ti: TimeInterval): Time {.
raises: [Exception], tags: [TimeEffect]
.}

subtracts the interval ti from Time t

echo getTime() - 1.day

  Source Edit
proc format(info: TimeInfo; f: string): string {.
raises: [ValueError], tags: []
.}
This function formats info as specified by f. The following format specifiers are available:
SpecifierDescriptionExample
dNumeric value of the day of the month, it will be one or two digits long.1/04/2012 -> 1, 21/04/2012 -> 21
ddSame as above, but always two digits.1/04/2012 -> 01, 21/04/2012 -> 21
dddThree letter string which indicates the day of the week.Saturday -> Sat, Monday -> Mon
ddddFull string for the day of the week.Saturday -> Saturday, Monday -> Monday
hThe hours in one digit if possible. Ranging from 0-12.5pm -> 5, 2am -> 2
hhThe hours in two digits always. If the hour is one digit 0 is prepended.5pm -> 05, 11am -> 11
HThe hours in one digit if possible, randing from 0-24.5pm -> 17, 2am -> 2
HHThe hours in two digits always. 0 is prepended if the hour is one digit.5pm -> 17, 2am -> 02
mThe minutes in 1 digit if possible.5:30 -> 30, 2:01 -> 1
mmSame as above but always 2 digits, 0 is prepended if the minute is one digit.5:30 -> 30, 2:01 -> 01
MThe month in one digit if possible.September -> 9, December -> 12
MMThe month in two digits always. 0 is prepended.September -> 09, December -> 12
MMMAbbreviated three-letter form of the month.September -> Sep, December -> Dec
MMMMFull month string, properly capitalized.September -> September
sSeconds as one digit if possible.00:00:06 -> 6
ssSame as above but always two digits. 0 is prepended.00:00:06 -> 06
tA when time is in the AM. P when time is in the PM.
ttSame as above, but AM and PM instead of A and P respectively.
y(yyyy)This displays the year to different digits. You most likely only want 2 or 4 'y's
yyDisplays the year to two digits.2012 -> 12
yyyyDisplays the year to four digits.2012 -> 2012
zDisplays the timezone offset from UTC.GMT+7 -> +7, GMT-5 -> -5
zzSame as above but with leading 0.GMT+7 -> +07, GMT-5 -> -05
zzzSame as above but with :mm where mm represents minutes.GMT+7 -> +07:00, GMT-5 -> -05:00

Other strings can be inserted by putting them in ''. For example hh'->'mm will give 01->56. The following characters can be inserted without quoting them: : - ( ) / [ ] ,. However you don't need to necessarily separate format specifiers, a unambiguous format string like yyyyMMddhhmmss is valid too.

  Source Edit
proc `$`(timeInfo: TimeInfo): string {.
tags: [], raises: [], gcsafe, locks: 0
.}
converts a TimeInfo object to a string representation. It uses the format yyyy-MM-dd'T'HH-mm-sszzz.   Source Edit
proc `$`(time: Time): string {.
tags: [TimeEffect], raises: [], gcsafe, locks: 0
.}
converts a Time value to a string representation. It will use the local time zone and use the format yyyy-MM-dd'T'HH-mm-sszzz.   Source Edit
proc parse(value, layout: string): TimeInfo {.
raises: [Exception, OverflowError, ValueError], tags: [TimeEffect]
.}
This function parses a date/time string using the standard format identifiers as listed below. The function defaults information not provided in the format string from the running program (timezone, month, year, etc). Daylight saving time is only set if no timezone is given and the given date lies within the DST period of the current locale.
SpecifierDescriptionExample
dNumeric value of the day of the month, it will be one or two digits long.1/04/2012 -> 1, 21/04/2012 -> 21
ddSame as above, but always two digits.1/04/2012 -> 01, 21/04/2012 -> 21
dddThree letter string which indicates the day of the week.Saturday -> Sat, Monday -> Mon
ddddFull string for the day of the week.Saturday -> Saturday, Monday -> Monday
hThe hours in one digit if possible. Ranging from 0-12.5pm -> 5, 2am -> 2
hhThe hours in two digits always. If the hour is one digit 0 is prepended.5pm -> 05, 11am -> 11
HThe hours in one digit if possible, randing from 0-24.5pm -> 17, 2am -> 2
HHThe hours in two digits always. 0 is prepended if the hour is one digit.5pm -> 17, 2am -> 02
mThe minutes in 1 digit if possible.5:30 -> 30, 2:01 -> 1
mmSame as above but always 2 digits, 0 is prepended if the minute is one digit.5:30 -> 30, 2:01 -> 01
MThe month in one digit if possible.September -> 9, December -> 12
MMThe month in two digits always. 0 is prepended.September -> 09, December -> 12
MMMAbbreviated three-letter form of the month.September -> Sep, December -> Dec
MMMMFull month string, properly capitalized.September -> September
sSeconds as one digit if possible.00:00:06 -> 6
ssSame as above but always two digits. 0 is prepended.00:00:06 -> 06
tA when time is in the AM. P when time is in the PM.
ttSame as above, but AM and PM instead of A and P respectively.
yyDisplays the year to two digits.2012 -> 12
yyyyDisplays the year to four digits.2012 -> 2012
zDisplays the timezone offset from UTC. Z is parsed as +0GMT+7 -> +7, GMT-5 -> -5
zzSame as above but with leading 0.GMT+7 -> +07, GMT-5 -> -05
zzzSame as above but with :mm where mm represents minutes.GMT+7 -> +07:00, GMT-5 -> -05:00

Other strings can be inserted by putting them in ''. For example hh'->'mm will give 01->56. The following characters can be inserted without quoting them: : - ( ) / [ ] ,. However you don't need to necessarily separate format specifiers, a unambiguous format string like yyyyMMddhhmmss is valid too.

  Source Edit
proc countLeapYears(yearSpan: int): int {.
raises: [], tags: []
.}

Returns the number of leap years spanned by a given number of years.

Note: For leap years, start date is assumed to be 1 AD. counts the number of leap years up to January 1st of a given year. Keep in mind that if specified year is a leap year, the leap day has not happened before January 1st of that year.

  Source Edit
proc countDays(yearSpan: int): int {.
raises: [], tags: []
.}
Returns the number of days spanned by a given number of years.   Source Edit
proc countYears(daySpan: int): int {.
raises: [], tags: []
.}
Returns the number of years spanned by a given number of days.   Source Edit
proc countYearsAndDays(daySpan: int): tuple[years: int, days: int] {.
raises: [], tags: []
.}
Returns the number of years spanned by a given number of days and the remainder as days.   Source Edit
proc getDayOfWeek(day, month, year: int): WeekDay {.
raises: [], tags: []
.}
Returns the day of the week enum from day, month and year.   Source Edit
proc getDayOfWeekJulian(day, month, year: int): WeekDay {.
raises: [], tags: []
.}
Returns the day of the week enum from day, month and year, according to the Julian calendar.   Source Edit
proc timeToTimeInfo(t: Time): TimeInfo {.
deprecated, raises: [], tags: []
.}

Converts a Time to TimeInfo.

Warning: This procedure is deprecated since version 0.14.0. Use getLocalTime or getGMTime instead.

  Source Edit
proc timeToTimeInterval(t: Time): TimeInterval {.
deprecated, raises: [], tags: [TimeEffect]
.}

Converts a Time to a TimeInterval.

Warning: This procedure is deprecated since version 0.14.0. Use toTimeInterval instead.

  Source Edit
proc toTimeInterval(t: Time): TimeInterval {.
raises: [], tags: [TimeEffect]
.}

Converts a Time to a TimeInterval.

To be used when diffing times.

let a = fromSeconds(1_000_000_000)
let b = fromSeconds(1_500_000_000)
echo a, " ", b  # real dates
echo a.toTimeInterval  # meaningless value, don't use it by itself
echo b.toTimeInterval - a.toTimeInterval
# (milliseconds: 0, seconds: -40, minutes: -6, hours: 1, days: -2, months: -2, years: 16)
  Source Edit
proc `-`(a, b: Time): int64 {.
gcsafe, extern: "ntDiffTime", tags: [], raises: [], noSideEffect, gcsafe, locks: 0
.}
computes the difference of two calendar times. Result is in seconds.
let a = fromSeconds(1_000_000_000)
let b = fromSeconds(1_500_000_000)
echo initInterval(seconds=int(b - a))
# (milliseconds: 0, seconds: 20, minutes: 53, hours: 0, days: 5787, months: 0, years: 0) 
  Source Edit
proc getStartMilsecs(): int {.
deprecated, tags: [TimeEffect], gcsafe, locks: 0, raises: []
.}
get the milliseconds from the start of the program. Deprecated since version 0.8.10. Use epochTime or cpuTime instead.   Source Edit
proc getTime(): Time {.
tags: [TimeEffect], gcsafe, locks: 0, raises: []
.}
gets the current calendar time as a UNIX epoch value (number of seconds elapsed since 1970) with integer precission. Use epochTime for higher resolution.   Source Edit
proc getLocalTime(t: Time): TimeInfo {.
tags: [TimeEffect], raises: [], gcsafe, locks: 0
.}
converts the calendar time t to broken-time representation, expressed relative to the user's specified time zone.   Source Edit
proc getGMTime(t: Time): TimeInfo {.
tags: [TimeEffect], raises: [], gcsafe, locks: 0
.}
converts the calendar time t to broken-down time representation, expressed in Coordinated Universal Time (UTC).   Source Edit
proc toTime(timeInfo: TimeInfo): Time {.
tags: [TimeEffect], gcsafe, locks: 0, raises: []
.}
converts a broken-down time structure to calendar time representation. The function ignores the specified contents of the structure members weekday and yearday and recomputes them from the other information in the broken-down time structure.   Source Edit
proc timeInfoToTime(timeInfo: TimeInfo): Time {.
tags: [TimeEffect], gcsafe, locks: 0, deprecated, raises: []
.}

converts a broken-down time structure to calendar time representation. The function ignores the specified contents of the structure members weekday and yearday and recomputes them from the other information in the broken-down time structure.

Warning: This procedure is deprecated since version 0.14.0. Use toTime instead.

  Source Edit
proc unixTimeToWinTime(t: Time): int64 {.
raises: [], tags: []
.}
converts a UNIX Time (time_t) to a Windows file time   Source Edit
proc winTimeToUnixTime(t: int64): Time {.
raises: [], tags: []
.}
converts a Windows time to a UNIX Time (time_t)   Source Edit
proc getTimezone(): int {.
tags: [TimeEffect], raises: [], gcsafe, locks: 0
.}
returns the offset of the local (non-DST) timezone in seconds west of UTC.   Source Edit
proc fromSeconds(since1970: float): Time {.
tags: [], raises: [], gcsafe, locks: 0
.}
Takes a float which contains the number of seconds since the unix epoch and returns a time object.   Source Edit
proc toSeconds(time: Time): float {.
tags: [], raises: [], gcsafe, locks: 0
.}
Returns the time in seconds since the unix epoch.   Source Edit
proc epochTime(): float {.
gcsafe, extern: "nt$1", tags: [TimeEffect], raises: []
.}
gets time after the UNIX epoch (1970) in seconds. It is a float because sub-second resolution is likely to be supported (depending on the hardware/OS).   Source Edit
proc cpuTime(): float {.
gcsafe, extern: "nt$1", tags: [TimeEffect], raises: []
.}
gets time spent that the CPU spent to run the current process in seconds. This may be more useful for benchmarking than epochTime. However, it may measure the real time instead (depending on the OS). The value of the result has no meaning. To generate useful timing values, take the difference between the results of two cpuTime calls:
var t0 = cpuTime()
doWork()
echo "CPU time [s] ", cpuTime() - t0
  Source Edit