This module contains routines and types for dealing with time using a proleptic Gregorian calendar. It's also available for the JavaScript target.
Although the types use nanosecond time resolution, the underlying resolution used by getTime() depends on the platform and backend (JS is limited to millisecond precision).
Examples:
import times, os let time = cpuTime() sleep(100) # replace this with something to be timed echo "Time taken: ",cpuTime() - time echo "My formatted time: ", format(now(), "d MMMM yyyy HH:mm") echo "Using predefined formats: ", getClockStr(), " ", getDateStr() echo "cpuTime() float value: ", cpuTime() echo "An hour from now : ", now() + 1.hours echo "An hour from (UTC) now: ", getTime().utc + initDuration(hours = 1)
The DateTime type can be parsed and formatted using the different parse and format procedures.
let dt = parse("2000-01-01", "yyyy-MM-dd")
echo dt.format("yyyy-MM-dd")
The different format patterns that are supported are documented below.
| Pattern | Description | Example |
|---|---|---|
d |
Numeric value representing the day of the month, it will be either one or two digits long. |
|
dd |
Same as above, but is always two digits. |
|
ddd |
Three letter string which indicates the day of the week. |
|
dddd |
Full string for the day of the week. |
|
h |
The hours in one digit if possible. Ranging from 1-12. |
|
hh |
The hours in two digits always. If the hour is one digit 0 is prepended. |
|
H |
The hours in one digit if possible, ranging from 0-23. |
|
HH |
The hours in two digits always. 0 is prepended if the hour is one digit. |
|
m |
The minutes in 1 digit if possible. |
|
mm |
Same as above but always 2 digits, 0 is prepended if the minute is one digit. |
|
M |
The month in one digit if possible. |
|
MM |
The month in two digits always. 0 is prepended. |
|
MMM |
Abbreviated three-letter form of the month. |
|
MMMM |
Full month string, properly capitalized. |
|
s |
Seconds as one digit if possible. |
|
ss |
Same as above but always two digits. 0 is prepended. |
|
t |
A when time is in the AM. P when time is in the PM. |
|
tt |
Same as above, but AM and PM instead of A and P respectively. |
|
yy |
The last two digits of the year. When parsing, the current century is assumed. |
|
yyyy |
The year, padded to atleast four digits. Is always positive, even when the year is BC. When the year is more than four digits, '+' is prepended. |
|
YYYY |
The year without any padding. Is always positive, even when the year is BC. |
|
uuuu |
The year, padded to atleast four digits. Will be negative when the year is BC. When the year is more than four digits, '+' is prepended unless the year is BC. |
|
UUUU |
The year without any padding. Will be negative when the year is BC. |
|
z |
Displays the timezone offset from UTC. |
|
zz |
Same as above but with leading 0. |
|
zzz |
Same as above but with :mm where mm represents minutes. |
|
zzzz |
Same as above but with :ss where ss represents seconds. |
|
g |
Era: AD or BC |
|
fff |
Milliseconds display |
|
ffffff |
Microseconds display |
|
fffffffff |
Nanoseconds display |
|
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: : - ( ) / [ ] ,. A literal ' can be specified with ''.
However you don't need to necessarily separate format patterns, a unambiguous format string like yyyyMMddhhmmss is valid too (although only for years in the range 1..9999).
Month = enum mJan = (1, "January"), mFeb = "February", mMar = "March", mApr = "April", mMay = "May", mJun = "June", mJul = "July", mAug = "August", mSep = "September", mOct = "October", mNov = "November", mDec = "December"
1, so ord(month) will give the month number in the range [1..12]. WeekDay = enum dMon = "Monday", dTue = "Tuesday", dWed = "Wednesday", dThu = "Thursday", dFri = "Friday", dSat = "Saturday", dSun = "Sunday"
MonthdayRange = range[1 .. 31]
HourRange = range[0 .. 23]
MinuteRange = range[0 .. 59]
SecondRange = range[0 .. 60]
YeardayRange = range[0 .. 365]
NanosecondRange = range[0 .. 999999999]
Time = object seconds: int64 nanosecond: NanosecondRange
DateTime = object of RootObj
nanosecond*: NanosecondRange ## The number of nanoseconds after the second,
## in the range 0 to 999_999_999.
second*: SecondRange ## The number of seconds after the minute,
## normally in the range 0 to 59, but can
## be up to 60 to allow for a leap second.
minute*: MinuteRange ## The number of minutes after the hour,
## in the range 0 to 59.
hour*: HourRange ## The number of hours past midnight,
## in the range 0 to 23.
monthday*: MonthdayRange ## The day of the month, in the range 1 to 31.
month*: Month ## The current month.
year*: int ## The current year, using astronomical year numbering
## (meaning that before year 1 is year 0, then year -1 and so on).
weekday*: WeekDay ## The current day of the week.
yearday*: YeardayRange ## The number of days since January 1,
## in the range 0 to 365.
isDst*: bool ## Determines whether DST is in effect.
## Always false for the JavaScript backend.
timezone*: Timezone ## The timezone represented as an implementation of ``Timezone``.
utcOffset*: int ## The offset in seconds west of UTC, including any offset due to DST.
## Note that the sign of this number is the opposite
## of the one in a formatted offset string like ``+01:00``
## (which would be parsed into the UTC offset ``-3600``).DateTime's returned by procedures in this module will never have a leap second. TimeInterval = object nanoseconds*: int ## The number of nanoseconds microseconds*: int ## The number of microseconds 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 weeks*: int ## The number of weeks months*: int ## The number of months years*: int ## The number of years
DateTime or Time. TimeInterval doesn't represent a fixed duration of time, since the duration of some units depend on the context (e.g a year can be either 365 or 366 days long). The non-fixed time units are years, months and days. Duration = object seconds: int64 nanosecond: NanosecondRange
Time. This type should be prefered over TimeInterval unless non-static time units is needed. TimeUnit = enum Nanoseconds, Microseconds, Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Months, Years
FixedTimeUnit = range[Nanoseconds .. Weeks]
TimeUnit that only includes units of fixed duration. These are the units that can be represented by a Duration. Timezone = ref object
zonedTimeFromTimeImpl: proc (x: Time): ZonedTime {...}{.tags: [], raises: [], gcsafe,
locks: 0.}
zonedTimeFromAdjTimeImpl: proc (x: Time): ZonedTime {...}{.tags: [], raises: [], gcsafe,
locks: 0.}
name: stringDateTime's of arbritary timezones. The times module only supplies implementations for the systems local time and UTC. ZonedTime = object
time*: Time ## The point in time being represented.
utcOffset*: int ## The offset in seconds west of UTC,
## including any offset due to DST.
isDst*: bool ## Determines whether DST is in effect.DurationParts = array[FixedTimeUnit, int64]
TimeIntervalParts = array[TimeUnit, int]
TimeFormat = object
patterns: seq[byte] ## \
## Contains the patterns encoded as bytes.
## Literal values are encoded in a special way.
## They start with ``Lit.byte``, then the length of the literal, then the
## raw char values of the literal. For example, the literal `foo` would
## be encoded as ``@[Lit.byte, 3.byte, 'f'.byte, 'o'.byte, 'o'.byte]``.
formatStr: stringDurationZero = (seconds: 0, nanosecond: 0)
doAssert initDuration(seconds = 1) > DurationZero doAssert initDuration(seconds = 0) == DurationZero
proc convert[T: SomeInteger](unitFrom, unitTo: FixedTimeUnit; quantity: T): T {...}{.inline.}Examples:
doAssert convert(Days, Hours, 2) == 48 doAssert convert(Days, Weeks, 13) == 1 doAssert convert(Seconds, Milliseconds, -1) == -1000
proc nanosecond(time: Time): NanosecondRange {...}{.raises: [], tags: [].}Time as the number of nanoseconds of the second. proc weeks(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}proc days(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}proc minutes(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}proc hours(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}proc seconds(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}proc milliseconds(dur: Duration): int {...}{.inline, raises: [], tags: [].}Examples:
let dur = initDuration(seconds = 1, milliseconds = 1) doAssert dur.milliseconds == 1
proc microseconds(dur: Duration): int {...}{.inline, raises: [], tags: [].}Examples:
let dur = initDuration(seconds = 1, microseconds = 1) doAssert dur.microseconds == 1
proc nanoseconds(dur: Duration): int {...}{.inline, raises: [], tags: [].}Examples:
let dur = initDuration(seconds = 1, nanoseconds = 1) doAssert dur.nanoseconds == 1
proc fractional(dur: Duration): Duration {...}{.inline, raises: [], tags: [].}Examples:
let dur = initDuration(seconds = 1, nanoseconds = 5) doAssert dur.fractional == initDuration(nanoseconds = 5)
proc fromUnix(unix: int64): Time {...}{.gcsafe, locks: 0, tags: [], raises: [], noSideEffect.}1970-01-01T00:00:00Z) to a Time. Examples:
doAssert $fromUnix(0).utc == "1970-01-01T00:00:00Z"
proc toUnix(t: Time): int64 {...}{.gcsafe, locks: 0, tags: [], raises: [], noSideEffect.}t to a unix timestamp (seconds since 1970-01-01T00:00:00Z). Examples:
doAssert fromUnix(0).toUnix() == 0
proc fromWinTime(win: int64): Time {...}{.raises: [], tags: [].}1601-01-01T00:00:00Z) to a Time. proc toWinTime(t: Time): int64 {...}{.raises: [], tags: [].}t to a Windows file time (100-nanosecond intervals since 1601-01-01T00:00:00Z). proc isLeapYear(year: int): bool {...}{.raises: [], tags: [].}year is a leap year. proc getDaysInMonth(month: Month; year: int): int {...}{.raises: [], tags: [].}month of a year. proc getDaysInYear(year: int): int {...}{.raises: [], tags: [].}year proc getDayOfYear(monthday: MonthdayRange; month: Month; year: int): YeardayRange {...}{.
tags: [], raises: [], gcsafe, locks: 0.}initDateTime(monthday, month, year, 0, 0, 0).yearday. proc getDayOfWeek(monthday: MonthdayRange; month: Month; year: int): WeekDay {...}{.tags: [],
raises: [], gcsafe, locks: 0.}initDateTime(monthday, month, year, 0, 0, 0).weekday. proc initDuration(nanoseconds, microseconds, milliseconds, seconds, minutes, hours,
days, weeks: int64 = 0): Duration {...}{.tags: [], raises: [], gcsafe,
locks: 0, noSideEffect.}Examples:
let dur = initDuration(seconds = 1, milliseconds = 1) doAssert dur.milliseconds == 1 doAssert dur.seconds == 1
proc toParts(dur: Duration): DurationParts {...}{.raises: [], tags: [].}Converts a duration into an array consisting of fixed time units.
Each value in the array gives information about a specific unit of time, for example result[Days] gives a count of days.
This procedure is useful for converting Duration values to strings.
Examples:
var dp = toParts(initDuration(weeks = 2, days = 1)) doAssert dp[Days] == 1 doAssert dp[Weeks] == 2 dp = toParts(initDuration(days = -1)) doAssert dp[Days] == -1
proc `$`(dur: Duration): string {...}{.raises: [], tags: [].}Duration. Examples:
doAssert $initDuration(seconds = 2) == "2 seconds"
doAssert $initDuration(weeks = 1, days = 2) == "1 week and 2 days"
doAssert $initDuration(hours = 1, minutes = 2, seconds = 3) ==
"1 hour, 2 minutes, and 3 seconds"
doAssert $initDuration(milliseconds = -1500) == "-1 second and -500 milliseconds" proc `+`(a, b: Duration): Duration {...}{.raises: [], tags: [].}Examples:
doAssert initDuration(seconds = 1) + initDuration(days = 1) ==
initDuration(seconds = 1, days = 1) proc `-`(a, b: Duration): Duration {...}{.raises: [], tags: [].}Examples:
doAssert initDuration(seconds = 1, days = 1) - initDuration(seconds = 1) ==
initDuration(days = 1) proc `-`(a: Duration): Duration {...}{.raises: [], tags: [].}Examples:
doAssert -initDuration(seconds = 1) == initDuration(seconds = -1)
proc `<`(a, b: Duration): bool {...}{.raises: [], tags: [].}a < b is true a might represent a larger absolute duration. Use abs(a) < abs(b) to compare the absolute duration. Examples:
doAssert initDuration(seconds = 1) < initDuration(seconds = 2) doAssert initDuration(seconds = -2) < initDuration(seconds = 1)
proc `<=`(a, b: Duration): bool {...}{.raises: [], tags: [].}proc `==`(a, b: Duration): bool {...}{.raises: [], tags: [].}proc `*`(a: int64; b: Duration): Duration {...}{.raises: [], tags: [].}Examples:
doAssert 5 * initDuration(seconds = 1) == initDuration(seconds = 5)
proc `*`(a: Duration; b: int64): Duration {...}{.raises: [], tags: [].}Examples:
doAssert initDuration(seconds = 1) * 5 == initDuration(seconds = 5)
proc `div`(a: Duration; b: int64): Duration {...}{.raises: [], tags: [].}Examples:
doAssert initDuration(seconds = 3) div 2 == initDuration(milliseconds = 1500) doAssert initDuration(nanoseconds = 3) div 2 == initDuration(nanoseconds = 1)
proc initTime(unix: int64; nanosecond: NanosecondRange): Time {...}{.tags: [], raises: [],
gcsafe, locks: 0, noSideEffect.}Time from a unix timestamp and a nanosecond part. proc `-`(a, b: Time): Duration {...}{.extern: "ntDiffTime", raises: [], tags: [].}proc `+`(a: Time; b: Duration): Time {...}{.extern: "ntAddTime", raises: [], tags: [].}Time. Examples:
doAssert (fromUnix(0) + initDuration(seconds = 1)) == fromUnix(1)
proc `-`(a: Time; b: Duration): Time {...}{.extern: "ntSubTime", raises: [], tags: [].}Time. Examples:
doAssert (fromUnix(0) - initDuration(seconds = 1)) == fromUnix(-1)
proc `<`(a, b: Time): bool {...}{.extern: "ntLtTime", raises: [], tags: [].}a < b, that is iff a happened before b. proc `<=`(a, b: Time): bool {...}{.extern: "ntLeTime", raises: [], tags: [].}a <= b. proc `==`(a, b: Time): bool {...}{.extern: "ntEqTime", raises: [], tags: [].}a == b, that is if both times represent the same point in time. proc high(typ: typedesc[Time]): Time
proc low(typ: typedesc[Time]): Time
proc high(typ: typedesc[Duration]): Duration
proc low(typ: typedesc[Duration]): Duration
proc abs(a: Duration): Duration {...}{.raises: [], tags: [].}Examples:
doAssert initDuration(milliseconds = -1500).abs ==
initDuration(milliseconds = 1500) proc toTime(dt: DateTime): Time {...}{.tags: [], raises: [], gcsafe, locks: 0.}proc newTimezone(name: string; zonedTimeFromTimeImpl: proc (time: Time): ZonedTime {...}{.
tags: [], raises: [], gcsafe, locks: 0.}; zonedTimeFromAdjTimeImpl: proc (
adjTime: Time): ZonedTime {...}{.tags: [], raises: [], gcsafe, locks: 0.}): Timezone {...}{.
raises: [], tags: [].}Create a new Timezone.
zonedTimeFromTimeImpl and zonedTimeFromAdjTimeImpl is used as the underlying implementations for zonedTimeFromTime and zonedTimeFromAdjTime.
If possible, the name parameter should match the name used in the tz database. If the timezone doesn't exist in the tz database, or if the timezone name is unknown, then any string that describes the timezone unambiguously can be used. Note that the timezones name is used for checking equality!
Examples:
proc utcTzInfo(time: Time): ZonedTime =
ZonedTime(utcOffset: 0, isDst: false, time: time)
let utc = newTimezone("Etc/UTC", utcTzInfo, utcTzInfo) proc name(zone: Timezone): string {...}{.raises: [], tags: [].}The name of the timezone.
If possible, the name will be the name used in the tz database. If the timezone doesn't exist in the tz database, or if the timezone name is unknown, then any string that describes the timezone unambiguously might be used. For example, the string "LOCAL" is used for the systems local timezone.
proc zonedTimeFromTime(zone: Timezone; time: Time): ZonedTime {...}{.raises: [], tags: [].}ZonedTime for some point in time. proc zonedTimeFromAdjTime(zone: Timezone; adjTime: Time): ZonedTime {...}{.raises: [],
tags: [].}Returns the ZonedTime for some local time.
Note that the Time argument does not represent a point in time, it represent a local time! E.g if adjTime is fromUnix(0), it should be interpreted as 1970-01-01T00:00:00 in the zone timezone, not in UTC.
proc `$`(zone: Timezone): string {...}{.raises: [], tags: [].}proc `==`(zone1, zone2: Timezone): bool {...}{.raises: [], tags: [].}Timezone's are considered equal if their name is equal. Examples:
doAssert local() == local() doAssert local() != utc()
proc inZone(time: Time; zone: Timezone): DateTime {...}{.tags: [], raises: [], gcsafe, locks: 0.}time into a DateTime using zone as the timezone. proc inZone(dt: DateTime; zone: Timezone): DateTime {...}{.tags: [], raises: [], gcsafe,
locks: 0.}DateTime representing the same point in time as dt but using zone as the timezone. proc utc(): Timezone {...}{.raises: [], tags: [].}Timezone implementation for the UTC timezone. Examples:
doAssert now().utc.timezone == utc() doAssert utc().name == "Etc/UTC"
proc local(): Timezone {...}{.raises: [], tags: [].}Timezone implementation for the local timezone. Examples:
doAssert now().timezone == local() doAssert local().name == "LOCAL"
proc utc(dt: DateTime): DateTime {...}{.raises: [], tags: [].}dt.inZone(utc()). proc local(dt: DateTime): DateTime {...}{.raises: [], tags: [].}dt.inZone(local()). proc utc(t: Time): DateTime {...}{.raises: [], tags: [].}t.inZone(utc()). proc local(t: Time): DateTime {...}{.raises: [], tags: [].}t.inZone(local()). proc getTime(): Time {...}{.tags: [TimeEffect], gcsafe, locks: 0, raises: [].}Time with nanosecond resolution. proc now(): DateTime {...}{.tags: [TimeEffect], gcsafe, locks: 0, raises: [].}Get the current time as a DateTime in the local timezone.
Shorthand for getTime().local.
proc initTimeInterval(nanoseconds, microseconds, milliseconds, seconds, minutes,
hours, days, weeks, 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.
Examples:
let day = initTimeInterval(hours = 24) let dt = initDateTime(1, mJan, 2000, 12, 0, 0, utc()) doAssert $(dt + day) == "2000-01-02T12:00:00Z"
proc `+`(ti1, ti2: TimeInterval): TimeInterval {...}{.raises: [], tags: [].}TimeInterval objects together. proc `-`(ti: TimeInterval): TimeInterval {...}{.raises: [], tags: [].}Examples:
let day = -initTimeInterval(hours = 24) doAssert day.hours == -24
proc `-`(ti1, ti2: TimeInterval): TimeInterval {...}{.raises: [], tags: [].}Subtracts TimeInterval ti1 from ti2.
Time components are subtracted one-by-one, see output:
Examples:
let ti1 = initTimeInterval(hours = 24) let ti2 = initTimeInterval(hours = 4) doAssert (ti1 - ti2) == initTimeInterval(hours = 20)
proc getDateStr(): string {...}{.gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [].}YYYY-MM-DD. proc getClockStr(): string {...}{.gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [].}HH:MM:SS. proc toParts(ti: TimeInterval): TimeIntervalParts {...}{.raises: [], tags: [].}Converts a TimeInterval into an array consisting of its time units, starting with nanoseconds and ending with years
This procedure is useful for converting TimeInterval values to strings. E.g. then you need to implement custom interval printing
Examples:
var tp = toParts(initTimeInterval(years = 1, nanoseconds = 123)) doAssert tp[Years] == 1 doAssert tp[Nanoseconds] == 123
proc `$`(ti: TimeInterval): string {...}{.raises: [], tags: [].}Examples:
doAssert $initTimeInterval(years = 1, nanoseconds = 123) ==
"1 year and 123 nanoseconds"
doAssert $initTimeInterval() == "0 nanoseconds" proc nanoseconds(nanos: int): TimeInterval {...}{.inline, raises: [], tags: [].}nanos nanoseconds. proc microseconds(micros: int): TimeInterval {...}{.inline, raises: [], tags: [].}micros microseconds. proc milliseconds(ms: int): TimeInterval {...}{.inline, raises: [], tags: [].}ms milliseconds. proc seconds(s: int): TimeInterval {...}{.inline, raises: [], tags: [].}TimeInterval of s seconds.
echo getTime() + 5.second
proc minutes(m: int): TimeInterval {...}{.inline, raises: [], tags: [].}TimeInterval of m minutes.
echo getTime() + 5.minutes
proc hours(h: int): TimeInterval {...}{.inline, raises: [], tags: [].}TimeInterval of h hours.
echo getTime() + 2.hours
proc days(d: int): TimeInterval {...}{.inline, raises: [], tags: [].}TimeInterval of d days.
echo getTime() + 2.days
proc weeks(w: int): TimeInterval {...}{.inline, raises: [], tags: [].}TimeInterval of w weeks.
echo getTime() + 2.weeks
proc months(m: int): TimeInterval {...}{.inline, raises: [], tags: [].}TimeInterval of m months.
echo getTime() + 2.months
proc years(y: int): TimeInterval {...}{.inline, raises: [], tags: [].}TimeInterval of y years.
echo getTime() + 2.years
proc initDateTime(monthday: MonthdayRange; month: Month; year: int; hour: HourRange;
minute: MinuteRange; second: SecondRange;
nanosecond: NanosecondRange; zone: Timezone = local()): DateTime {...}{.
raises: [], tags: [].}DateTime in the specified timezone. Examples:
let dt1 = initDateTime(30, mMar, 2017, 0, 0, 0, 0, utc()) doAssert $dt1 == "2017-03-30T00:00:00Z"
proc initDateTime(monthday: MonthdayRange; month: Month; year: int; hour: HourRange;
minute: MinuteRange; second: SecondRange; zone: Timezone = local()): DateTime {...}{.
raises: [], tags: [].}DateTime in the specified timezone. Examples:
let dt1 = initDateTime(30, mMar, 2017, 0, 0, 0, utc()) doAssert $dt1 == "2017-03-30T00:00:00Z"
proc `+`(dt: DateTime; interval: TimeInterval): DateTime {...}{.raises: [], tags: [].}Adds interval to dt. Components from interval are added in the order of their size, i.e first the years component, then the months component and so on. The returned DateTime will have the same timezone as the input.
Note that when adding months, monthday overflow is allowed. This means that if the resulting month doesn't have enough days it, the month will be incremented and the monthday will be set to the number of days overflowed. So adding one month to 31 October will result in 31 November, which will overflow and result in 1 December.
Examples:
let dt = initDateTime(30, mMar, 2017, 0, 0, 0, utc()) doAssert $(dt + 1.months) == "2017-04-30T00:00:00Z" doAssert $(dt - 1.months) == "2017-03-02T00:00:00Z"
proc `-`(dt: DateTime; interval: TimeInterval): DateTime {...}{.raises: [], tags: [].}interval from dt. Components from interval are subtracted in the order of their size, i.e first the years component, then the months component and so on. The returned DateTime will have the same timezone as the input. Examples:
let dt = initDateTime(30, mMar, 2017, 0, 0, 0, utc()) doAssert $(dt - 5.days) == "2017-03-25T00:00:00Z"
proc `+`(dt: DateTime; dur: Duration): DateTime {...}{.raises: [], tags: [].}Examples:
let dt = initDateTime(30, mMar, 2017, 0, 0, 0, utc()) let dur = initDuration(hours = 5) doAssert $(dt + dur) == "2017-03-30T05:00:00Z"
proc `-`(dt: DateTime; dur: Duration): DateTime {...}{.raises: [], tags: [].}Examples:
let dt = initDateTime(30, mMar, 2017, 0, 0, 0, utc()) let dur = initDuration(days = 5) doAssert $(dt - dur) == "2017-03-25T00:00:00Z"
proc `-`(dt1, dt2: DateTime): Duration {...}{.raises: [], tags: [].}dt1 and dt2. Examples:
let dt1 = initDateTime(30, mMar, 2017, 0, 0, 0, utc()) let dt2 = initDateTime(25, mMar, 2017, 0, 0, 0, utc()) doAssert dt1 - dt2 == initDuration(days = 5)
proc `<`(a, b: DateTime): bool {...}{.raises: [], tags: [].}a < b, that is iff a happened before b. proc `<=`(a, b: DateTime): bool {...}{.raises: [], tags: [].}a <= b. proc `==`(a, b: DateTime): bool {...}{.raises: [], tags: [].}a == b, that is if both dates represent the same point in time. proc between(startDt, endDt: DateTime): TimeInterval {...}{.raises: [], tags: [].}Evaluate difference between two dates in TimeInterval format, so, it will be relative.
Warning: It's not recommended to use between for DateTime's in different TimeZone's. a + between(a, b) == b is only guaranteed when a and b are in UTC.
Examples:
var a = initDateTime(year = 2018, month = Month(3), monthday = 25, hour = 0, minute = 59,
second = 59, nanosecond = 1, zone = utc()).local
var b = initDateTime(year = 2018, month = Month(3), monthday = 25, hour = 1, minute = 1,
second = 1, nanosecond = 0, zone = utc()).local
doAssert between(a, b) ==
initTimeInterval(nanoseconds = 999, milliseconds = 999, microseconds = 999,
seconds = 1, minutes = 1)
a = parse("2018-01-09T00:00:00+00:00", "yyyy-MM-dd\'T\'HH:mm:sszzz", utc())
b = parse("2018-01-10T23:00:00-02:00", "yyyy-MM-dd\'T\'HH:mm:sszzz")
doAssert between(a, b) == initTimeInterval(hours = 1, days = 2)
## Though, here correct answer should be 1 day 25 hours (cause this day in
## this tz is actually 26 hours). That's why operating different TZ is
## discouraged proc `+`(time: Time; interval: TimeInterval): Time {...}{.raises: [], tags: [].}Examples:
let tm = fromUnix(0) doAssert tm + 5.seconds == fromUnix(5)
proc `-`(time: Time; interval: TimeInterval): Time {...}{.raises: [], tags: [].}Examples:
let tm = fromUnix(5) doAssert tm - 5.seconds == fromUnix(0)
proc `+=`[T, U: TimesMutableTypes](a: var T; b: U)
a in place by adding b. Examples:
var tm = fromUnix(0) tm += initDuration(seconds = 1) doAssert tm == fromUnix(1)
proc `-=`[T, U: TimesMutableTypes](a: var T; b: U)
a in place by subtracting b. Examples:
var tm = fromUnix(5) tm -= initDuration(seconds = 5) doAssert tm == fromUnix(0)
proc `*=`[T: TimesMutableTypes; U](a: var T; b: U)
Examples:
var dur = initDuration(seconds = 1) dur *= 5 doAssert dur == initDuration(seconds = 5)
proc `$`(f: TimeFormat): string {...}{.raises: [], tags: [].}f. Examples:
let f = initTimeFormat("yyyy-MM-dd")
doAssert $f == "yyyy-MM-dd" proc initTimeFormat(format: string): TimeFormat {...}{.raises: [ValueError], tags: [].}Construct a new time format for parsing & formatting time types.
See Parsing and formatting dates for documentation of the format argument.
Examples:
let f = initTimeFormat("yyyy-MM-dd")
doAssert "2000-01-01" == "2000-01-01".parse(f).format(f) proc format(dt: DateTime; f: TimeFormat): string {...}{.raises: [], tags: [].}dt using the format specified by f. Examples:
let f = initTimeFormat("yyyy-MM-dd")
let dt = initDateTime(1, mJan, 2000, 0, 0, 0, utc())
doAssert "2000-01-01" == dt.format(f) proc format(dt: DateTime; f: string): string {...}{.raises: [ValueError], tags: [].}Shorthand for constructing a TimeFormat and using it to format dt.
See Parsing and formatting dates for documentation of the format argument.
Examples:
let dt = initDateTime(1, mJan, 2000, 0, 0, 0, utc()) doAssert "2000-01-01" == format(dt, "yyyy-MM-dd")
proc format(dt: DateTime; f: static[string]): string {...}{.raises: [].}format at compile time. proc format(time: Time; f: string; zone: Timezone = local()): string {...}{.tags: [],
raises: [ValueError].}Shorthand for constructing a TimeFormat and using it to format time. Will use the timezone specified by zone.
See Parsing and formatting dates for documentation of the f argument.
Examples:
var dt = initDateTime(1, mJan, 1970, 0, 0, 0, utc()) var tm = dt.toTime() doAssert format(tm, "yyyy-MM-dd\'T\'HH:mm:ss", utc()) == "1970-01-01T00:00:00"
proc format(time: Time; f: static[string]; zone: Timezone = local()): string {...}{.tags: [].}f at compile time. proc parse(input: string; f: TimeFormat; zone: Timezone = local()): DateTime {...}{.
raises: [ValueError, OverflowError, UnpackError], tags: [TimeEffect].}input as a DateTime using the format specified by f. If no UTC offset was parsed, then input is assumed to be specified in the zone timezone. If a UTC offset was parsed, the result will be converted to the zone timezone. Examples:
let f = initTimeFormat("yyyy-MM-dd")
let dt = initDateTime(1, mJan, 2000, 0, 0, 0, utc())
doAssert dt == "2000-01-01".parse(f, utc()) proc parse(input, f: string; tz: Timezone = local()): DateTime {...}{.
raises: [ValueError, OverflowError, UnpackError], tags: [TimeEffect].}Shorthand for constructing a TimeFormat and using it to parse input as a DateTime.
See Parsing and formatting dates for documentation of the f argument.
Examples:
let dt = initDateTime(1, mJan, 2000, 0, 0, 0, utc())
doAssert dt == parse("2000-01-01", "yyyy-MM-dd", utc()) proc parse(input: string; f: static[string]; zone: Timezone = local()): DateTime
f at compile time. proc parseTime(input, f: string; zone: Timezone): Time {...}{.
raises: [ValueError, OverflowError, UnpackError], tags: [TimeEffect].}Shorthand for constructing a TimeFormat and using it to parse input as a DateTime, then converting it a Time.
See Parsing and formatting dates for documentation of the format argument.
Examples:
let tStr = "1970-01-01T00:00:00+00:00" doAssert parseTime(tStr, "yyyy-MM-dd\'T\'HH:mm:sszzz", utc()) == fromUnix(0)
proc parseTime(input: string; f: static[string]; zone: Timezone): Time
format at compile time. proc `$`(dt: DateTime): string {...}{.tags: [], raises: [], gcsafe, locks: 0.}yyyy-MM-dd'T'HH-mm-sszzz. Examples:
let dt = initDateTime(1, mJan, 2000, 12, 0, 0, utc()) doAssert $dt == "2000-01-01T12:00:00Z"
proc `$`(time: Time): string {...}{.tags: [], raises: [], gcsafe, locks: 0.}yyyy-MM-dd'T'HH-mm-sszzz. Examples:
let dt = initDateTime(1, mJan, 1970, 0, 0, 0, local()) let tm = dt.toTime() doAssert $tm == "1970-01-01T00:00:00" & format(dt, "zzz")
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.
proc countDays(yearSpan: int): int {...}{.raises: [], tags: [].}proc countYears(daySpan: int): int {...}{.raises: [], tags: [].}proc countYearsAndDays(daySpan: int): tuple[years: int, days: int] {...}{.raises: [], tags: [].}proc toTimeInterval(time: Time): TimeInterval {...}{.raises: [], tags: [].}Converts a Time to a TimeInterval.
To be used when diffing times. Consider using between instead.
Examples:
let a = fromUnix(10) let b = fromUnix(1500000000) let ti = b.toTimeInterval() - a.toTimeInterval() doAssert a + ti == b
proc cpuTime(): float {...}{.gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [].}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: Examples:
var t0 = cpuTime() var fib = @[0, 1, 1] for i in 1 .. 10: fib.add(fib[^1] + fib[^2]) echo "CPU time [s] ", cpuTime() - t0 echo "Fib is [s] ", fib
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).
getTime should generally be prefered over this proc.
proc unixTimeToWinTime(time: CTime): int64 {...}{.deprecated: "Use toWinTime instead",
raises: [], tags: [].}Converts a UNIX Time (time_t) to a Windows file time
Deprecated: use toWinTime instead.
proc winTimeToUnixTime(time: int64): CTime {...}{.deprecated: "Use fromWinTime instead",
raises: [], tags: [].}Converts a Windows time to a UNIX Time (time_t)
Deprecated: use fromWinTime instead.
proc initInterval(seconds, minutes, hours, days, months, years: int = 0): TimeInterval {...}{.
deprecated, raises: [], tags: [].}initTimeInterval instead. proc fromSeconds(since1970: float): Time {...}{.tags: [], raises: [], gcsafe, locks: 0,
deprecated.}Takes a float which contains the number of seconds since the unix epoch and returns a time object.
Deprecated since v0.18.0: use fromUnix instead
proc fromSeconds(since1970: int64): Time {...}{.tags: [], raises: [], gcsafe, locks: 0,
deprecated.}Takes an int which contains the number of seconds since the unix epoch and returns a time object.
Deprecated since v0.18.0: use fromUnix instead
proc toSeconds(time: Time): float {...}{.tags: [], raises: [], gcsafe, locks: 0, deprecated.}Returns the time in seconds since the unix epoch.
Deprecated since v0.18.0: use toUnix instead
proc getLocalTime(time: Time): DateTime {...}{.tags: [], raises: [], gcsafe, locks: 0,
deprecated.}Converts the calendar time time to broken-time representation, expressed relative to the user's specified time zone.
Deprecated since v0.18.0: use local instead
proc getGMTime(time: Time): DateTime {...}{.tags: [], raises: [], gcsafe, locks: 0, deprecated.}Converts the calendar time time to broken-down time representation, expressed in Coordinated Universal Time (UTC).
Deprecated since v0.18.0: use utc instead
proc getTimezone(): int {...}{.tags: [TimeEffect], raises: [], gcsafe, locks: 0, deprecated.}Returns the offset of the local (non-DST) timezone in seconds west of UTC.
Deprecated since v0.18.0: use now().utcOffset to get the current utc offset (including DST).
proc timeInfoToTime(dt: DateTime): Time {...}{.tags: [], gcsafe, locks: 0, deprecated,
raises: [].}Converts a broken-down time structure to calendar time representation.
Deprecated since v0.14.0: use toTime instead.
proc getStartMilsecs(): int {...}{.deprecated, tags: [TimeEffect], gcsafe, locks: 0,
raises: [].}get the milliseconds from the start of the program.
Deprecated since v0.8.10: use epochTime or cpuTime instead.
proc timeToTimeInterval(t: Time): TimeInterval {...}{.deprecated, raises: [], tags: [].}Converts a Time to a TimeInterval.
Deprecated since v0.14.0: use toTimeInterval instead.
proc getDayOfWeek(day, month, year: int): WeekDay {...}{.tags: [], raises: [], gcsafe, locks: 0,
deprecated.}getDayOfWeek(monthday: MonthdayRange; month: Month; year: int) instead. proc getDayOfWeekJulian(day, month, year: int): WeekDay {...}{.deprecated, raises: [],
tags: [].}proc adjTime(zt: ZonedTime): Time {...}{.deprecated: "Use zt.time instead", raises: [],
tags: [].}time field instead. proc adjTime=(zt: var ZonedTime; adjTime: Time) {...}{.deprecated: "Use zt.time instead",
raises: [], tags: [].}time field instead. proc zoneInfoFromUtc(zone: Timezone; time: Time): ZonedTime {...}{.
deprecated: "Use zonedTimeFromTime instead", raises: [], tags: [].}zonedTimeFromTime instead. proc zoneInfoFromTz(zone: Timezone; adjTime: Time): ZonedTime {...}{.
deprecated: "Use zonedTimeFromAdjTime instead", raises: [], tags: [].}zonedTimeFromAdjTime instead.
© 2006–2018 Andreas Rumpf
Licensed under the MIT License.
https://nim-lang.org/docs/times.html