The times module contains routines and types for dealing with time using the proleptic Gregorian calendar. It's also available for the JavaScript target.
Although the times module supports nanosecond time resolution, the resolution used by getTime() depends on the platform and backend (JS is limited to millisecond precision).
Examples
import std/[times, os] # Simple benchmarking let time = cpuTime() sleep(100) # Replace this with something to be timed echo "Time taken: ", cpuTime() - time # Current date & time let now1 = now() # Current timestamp as a DateTime in local time let now2 = now().utc # Current timestamp as a DateTime in UTC let now3 = getTime() # Current timestamp as a Time # Arithmetic using Duration echo "One hour from now : ", now() + initDuration(hours = 1) # Arithmetic using TimeInterval echo "One year from now : ", now() + 1.years echo "One month from now : ", now() + 1.months
Parsing and Formatting Dates
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. | 1/04/2012 -> 1 |
dd | Same as above, but is always two digits. | 1/04/2012 -> 01 |
ddd | Three letter string which indicates the day of the week. | Saturday -> Sat |
dddd | Full string for the day of the week. | Saturday -> Saturday |
GG | The last two digits of the Iso Week-Year | 30/12/2012 -> 13 |
GGGG | The Iso week-calendar year padded to four digits | 30/12/2012 -> 2013 |
h | The hours in one digit if possible. Ranging from 1-12. | 5pm -> 5 |
hh | The hours in two digits always. If the hour is one digit, 0 is prepended. | 5pm -> 05 |
H | The hours in one digit if possible, ranging from 0-23. | 5pm -> 17 |
HH | The hours in two digits always. 0 is prepended if the hour is one digit. | 5pm -> 17 |
m | The minutes in one digit if possible. | 5:30 -> 30 |
mm | Same as above but always two digits, 0 is prepended if the minute is one digit. | 5:30 -> 30 |
M | The month in one digit if possible. | September -> 9 |
MM | The month in two digits always. 0 is prepended if the month value is one digit. | September -> 09 |
MMM | Abbreviated three-letter form of the month. | September -> Sep |
MMMM | Full month string, properly capitalized. | September -> September |
s | Seconds as one digit if possible. | 00:00:06 -> 6 |
ss | Same as above but always two digits. 0 is prepended if the second is one digit. | 00:00:06 -> 06 |
t | A when time is in the AM. P when time is in the PM. | 5pm -> P |
tt | Same as above, but AM and PM instead of A and P respectively. | 5pm -> PM |
yy | The last two digits of the year. When parsing, the current century is assumed. | 2012 AD -> 12 |
yyyy | The year, padded to at least four digits. Is always positive, even when the year is BC. When the year is more than four digits, '+' is prepended. | 2012 AD -> 2012 |
YYYY | The year without any padding. Is always positive, even when the year is BC. | 2012 AD -> 2012 |
uuuu | The year, padded to at least 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. | 2012 AD -> 2012 |
UUUU | The year without any padding. Will be negative when the year is BC. | 2012 AD -> 2012 |
V | The Iso Week-Number as one or two digits | 3/2/2012 -> 5 |
VV | The Iso Week-Number as two digits always. 0 is prepended if one digit. | 3/2/2012 -> 05 |
z | Displays the timezone offset from UTC. | UTC+7 -> +7 |
zz | Same as above but with leading 0. | UTC+7 -> +07 |
zzz | Same as above but with :mm where mm represents minutes. | UTC+7 -> +07:00 |
ZZZ | Same as above but with mm where mm represents minutes. | UTC+7 -> +0700 |
zzzz | Same as above but with :ss where ss represents seconds. | UTC+7 -> +07:00:00 |
ZZZZ | Same as above but with ss where ss represents seconds. | UTC+7 -> +070000 |
g | Era: AD or BC | 300 AD -> AD |
fff | Milliseconds display | 1000000 nanoseconds -> 1 |
ffffff | Microseconds display | 1000000 nanoseconds -> 1000 |
fffffffff | Nanoseconds display | 1000000 nanoseconds -> 1000000 |
Other strings can be inserted by putting them in ''. For example hh'->'mm will give 01->56. In addition to spaces, 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, as an unambiguous format string like yyyyMMddhhmmss is also valid (although only for years in the range 1..9999).
Duration vs TimeInterval
The times module exports two similar types that are both used to represent some amount of time: Duration and TimeInterval. This section explains how they differ and when one should be preferred over the other (short answer: use Duration unless support for months and years is needed).
Duration
A Duration represents a duration of time stored as seconds and nanoseconds. A Duration is always fully normalized, so initDuration(hours = 1) and initDuration(minutes = 60) are equivalent.
Arithmetic with a Duration is very fast, especially when used with the Time type, since it only involves basic arithmetic. Because Duration is more performant and easier to understand it should generally preferred.
TimeInterval
A TimeInterval represents an amount of time expressed in calendar units, for example "1 year and 2 days". Since some units cannot be normalized (the length of a year is different for leap years for example), the TimeInterval type uses separate fields for every unit. The TimeInterval's returned from this module generally don't normalize anything, so even units that could be normalized (like seconds, milliseconds and so on) are left untouched.
Arithmetic with a TimeInterval can be very slow, because it requires timezone information.
Since it's slower and more complex, the TimeInterval type should be avoided unless the program explicitly needs the features it offers that Duration doesn't have.
How long is a day?
It should be especially noted that the handling of days differs between TimeInterval and Duration. The Duration type always treats a day as exactly 86400 seconds. For TimeInterval, it's more complex.
As an example, consider the amount of time between these two timestamps, both in the same timezone:
- 2018-03-25T12:00+02:00
- 2018-03-26T12:00+01:00
If only the date & time is considered, it appears that exactly one day has passed. However, the UTC offsets are different, which means that the UTC offset was changed somewhere in between. This happens twice each year for timezones that use daylight savings time. Because of this change, the amount of time that has passed is actually 25 hours.
The TimeInterval type uses calendar units, and will say that exactly one day has passed. The Duration type on the other hand normalizes everything to seconds, and will therefore say that 90000 seconds has passed, which is the same as 25 hours.
See also
Types
- Represents a time in different parts. Although this type can represent leap seconds, they are generally not supported in this module. They are not ignored, but the DateTime's returned by procedures in this module will never have a leap second. Source Edit
Duration = object
-
Represents a fixed duration of time, meaning a duration that has constant length independent of the context.
To create a new Duration, use initDuration. Instead of trying to access the private attributes, use inSeconds for converting to seconds and inNanoseconds for converting to nanoseconds.
Source Edit DurationParts = array[FixedTimeUnit, int64]
- Source Edit
FixedTimeUnit = range[Nanoseconds .. Weeks]
- Subrange of TimeUnit that only includes units of fixed duration. These are the units that can be represented by a Duration. Source Edit
IsoWeekRange = range[1 .. 53]
- An ISO 8601 calendar week number. Source Edit
-
An ISO 8601 calendar year number.Warning: The ISO week-based year can correspond to the following or previous year from 29 December to January 3.Source Edit
MinuteRange = range[0 .. 59]
- Source Edit
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"
- Represents a month. Note that the enum starts at 1, so ord(month) will give the month number in the range 1..12. Source Edit
MonthdayRange = range[1 .. 31]
- Source Edit
NanosecondRange = range[0 .. 999999999]
- Source Edit
SecondRange = range[0 .. 60]
- Includes the value 60 to allow for a leap second. Note however that the second of a DateTime will never be a leap second. Source Edit
TimeFormat = object ## \ ## 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]`.
-
Represents a format for parsing and printing time types.
To create a new TimeFormat use initTimeFormat proc.
Source Edit TimeFormatParseError = object of ValueError
- Raised when parsing a TimeFormat string fails. Source Edit
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
-
Represents a non-fixed duration of time. Can be used to add and subtract non-fixed time units from a DateTime or Time.
Create a new TimeInterval with initTimeInterval proc.
Note that 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, days and week.
Note that TimeInterval's returned from the times module are never normalized. If you want to normalize a time unit, Duration should be used instead.
Source Edit TimeIntervalParts = array[TimeUnit, int]
- Source Edit
TimeParseError = object of ValueError
- Raised when parsing input using a TimeFormat fails. Source Edit
TimeUnit = enum Nanoseconds, Microseconds, Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Months, Years
- Different units of time. Source Edit
Timezone = ref object
- Timezone interface for supporting DateTimes of arbitrary timezones. The times module only supplies implementations for the system's local time and UTC. Source Edit
WeekDay = enum dMon = "Monday", dTue = "Tuesday", dWed = "Wednesday", dThu = "Thursday", dFri = "Friday", dSat = "Saturday", dSun = "Sunday"
- Represents a weekday. Source Edit
YeardayRange = range[0 .. 365]
- Source Edit
Consts
DefaultLocale = (MMM: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], MMMM: ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"], ddd: ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"], dddd: [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"])
- Source Edit
DurationZero = (seconds: 0, nanosecond: 0)
-
Zero value for durations. Useful for comparisons.
Source EditdoAssert initDuration(seconds = 1) > DurationZero doAssert initDuration(seconds = 0) == DurationZero
Procs
-
Converts a DateTime object to a string representation. It uses the format yyyy-MM-dd'T'HH:mm:sszzz.
Example:
Source Editlet dt = dateTime(2000, mJan, 01, 12, 00, 00, 00, utc()) doAssert $dt == "2000-01-01T12:00:00Z" doAssert $default(DateTime) == "Uninitialized DateTime"
-
Human friendly string representation of a Duration.
Example:
Source EditdoAssert $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 `$`(f: TimeFormat): string {....raises: [], tags: [], forbids: [].}
-
Returns the format string that was used to construct f.
Example:
Source Editlet f = initTimeFormat("yyyy-MM-dd") doAssert $f == "yyyy-MM-dd"
proc `$`(ti: TimeInterval): string {....raises: [], tags: [], forbids: [].}
-
Get string representation of TimeInterval.
Example:
Source EditdoAssert $initTimeInterval(years = 1, nanoseconds = 123) == "1 year and 123 nanoseconds" doAssert $initTimeInterval() == "0 nanoseconds"
-
Multiply a duration by some scalar.
Example:
Source EditdoAssert initDuration(seconds = 1) * 5 == initDuration(seconds = 5) doAssert initDuration(minutes = 45) * 3 == initDuration(hours = 2, minutes = 15)
-
Add two durations together.
Example:
Source EditdoAssert initDuration(seconds = 1) + initDuration(days = 1) == initDuration(seconds = 1, days = 1)
-
Add a duration of time to a Time.
Example:
Source EditdoAssert (fromUnix(0) + initDuration(seconds = 1)) == fromUnix(1)
-
Example:
Source Editlet dt = dateTime(2017, mMar, 30, 00, 00, 00, 00, utc()) let dur = initDuration(hours = 5) doAssert $(dt + dur) == "2017-03-30T05:00:00Z"
proc `+`(dt: DateTime; interval: TimeInterval): DateTime {....raises: [], tags: [], forbids: [].}
-
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.
Example:
Source Editlet dt = dateTime(2017, mMar, 30, 00, 00, 00, 00, utc()) doAssert $(dt + 1.months) == "2017-04-30T00:00:00Z" # This is correct and happens due to monthday overflow. doAssert $(dt - 1.months) == "2017-03-02T00:00:00Z"
proc `+`(ti1, ti2: TimeInterval): TimeInterval {....raises: [], tags: [], forbids: [].}
- Adds two TimeInterval objects together. Source Edit
proc `+=`(a: var DateTime; b: TimeInterval) {....raises: [], tags: [], forbids: [].}
- Source Edit
proc `+=`(a: var TimeInterval; b: TimeInterval) {....raises: [], tags: [], forbids: [].}
- Source Edit
proc `+=`(t: var Time; b: TimeInterval) {....raises: [], tags: [], forbids: [].}
- Source Edit
-
Subtract a duration from another.
Example:
Source EditdoAssert initDuration(seconds = 1, days = 1) - initDuration(seconds = 1) == initDuration(days = 1)
-
Computes the duration between two points in time.
Example:
Source EditdoAssert initTime(1000, 100) - initTime(500, 20) == initDuration(minutes = 8, seconds = 20, nanoseconds = 80)
-
Reverse a duration.
Example:
Source EditdoAssert -initDuration(seconds = 1) == initDuration(seconds = -1)
-
Subtracts a duration of time from a Time.
Example:
Source EditdoAssert (fromUnix(0) - initDuration(seconds = 1)) == fromUnix(-1)
-
Compute the duration between dt1 and dt2.
Example:
Source Editlet dt1 = dateTime(2017, mMar, 30, 00, 00, 00, 00, utc()) let dt2 = dateTime(2017, mMar, 25, 00, 00, 00, 00, utc()) doAssert dt1 - dt2 == initDuration(days = 5)
-
Example:
Source Editlet dt = dateTime(2017, mMar, 30, 00, 00, 00, 00, utc()) let dur = initDuration(days = 5) doAssert $(dt - dur) == "2017-03-25T00:00:00Z"
proc `-`(dt: DateTime; interval: TimeInterval): DateTime {....raises: [], tags: [], forbids: [].}
-
Subtract 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.
Example:
Source Editlet dt = dateTime(2017, mMar, 30, 00, 00, 00, 00, utc()) doAssert $(dt - 5.days) == "2017-03-25T00:00:00Z"
proc `-`(ti1, ti2: TimeInterval): TimeInterval {....raises: [], tags: [], forbids: [].}
-
Subtracts TimeInterval ti1 from ti2.
Time components are subtracted one-by-one, see output:
Example:
Source Editlet ti1 = initTimeInterval(hours = 24) let ti2 = initTimeInterval(hours = 4) doAssert (ti1 - ti2) == initTimeInterval(hours = 20)
proc `-`(ti: TimeInterval): TimeInterval {....raises: [], tags: [], forbids: [].}
-
Reverses a time interval
Example:
Source Editlet day = -initTimeInterval(hours = 24) doAssert day.hours == -24
proc `-`(time: Time; interval: TimeInterval): Time {....raises: [], tags: [], forbids: [].}
-
Subtracts interval from Time time. If interval contains any years, months, weeks or days the operation is performed in the local timezone.
Example:
Source Editlet tm = fromUnix(5) doAssert tm - 5.seconds == fromUnix(0)
proc `-=`(a: var DateTime; b: TimeInterval) {....raises: [], tags: [], forbids: [].}
- Source Edit
proc `-=`(a: var TimeInterval; b: TimeInterval) {....raises: [], tags: [], forbids: [].}
- Source Edit
proc `-=`(t: var Time; b: TimeInterval) {....raises: [], tags: [], forbids: [].}
- Source Edit
-
Note that a duration can be negative, so even if a < b is true a might represent a larger absolute duration. Use abs(a) < abs(b) to compare the absolute duration.
Example:
Source EditdoAssert initDuration(seconds = 1) < initDuration(seconds = 2) doAssert initDuration(seconds = -2) < initDuration(seconds = 1) doAssert initDuration(seconds = -2).abs < initDuration(seconds = 1).abs == false
proc between(startDt, endDt: DateTime): TimeInterval {....raises: [], tags: [], forbids: [].}
-
Gives the difference between startDt and endDt as a TimeInterval. The following guarantees about the result is given:
- All fields will have the same sign.
- If startDt.timezone == endDt.timezone, it is guaranteed that startDt + between(startDt, endDt) == endDt.
- If startDt.timezone != endDt.timezone, then the result will be equivalent to between(startDt.utc, endDt.utc).
Example:
Source Editvar a = dateTime(2015, mMar, 25, 12, 0, 0, 00, utc()) var b = dateTime(2017, mApr, 1, 15, 0, 15, 00, utc()) var ti = initTimeInterval(years = 2, weeks = 1, hours = 3, seconds = 15) doAssert between(a, b) == ti doAssert between(a, b) == -between(b, a)
proc convert[T: SomeInteger](unitFrom, unitTo: FixedTimeUnit; quantity: T): T {. inline.}
-
Convert a quantity of some duration unit to another duration unit. This proc only deals with integers, so the result might be truncated.
Example:
Source EditdoAssert convert(Days, Hours, 2) == 48 doAssert convert(Days, Weeks, 13) == 1 # Truncated doAssert convert(Seconds, Milliseconds, -1) == -1000
proc cpuTime(): float {....tags: [TimeEffect], raises: [], forbids: [].}
-
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:
Example:
When the flag --benchmarkVM is passed to the compiler, this proc is also available at compile time Source Editvar t0 = cpuTime() # some useless work here (calculate fibonacci) 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 dateTime(year: int; month: Month; monthday: MonthdayRange; hour: HourRange = 0; minute: MinuteRange = 0; second: SecondRange = 0; nanosecond: NanosecondRange = 0; zone: Timezone = local()): DateTime {....raises: [], tags: [], forbids: [].}
-
Create a new DateTime in the specified timezone.
Example:
Source Editassert $dateTime(2017, mMar, 30, zone = utc()) == "2017-03-30T00:00:00Z"
proc days(d: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
-
TimeInterval of d days.
echo getTime() + 2.days
Source Edit proc epochTime(): float {....tags: [TimeEffect], raises: [], forbids: [].}
-
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 preferred over this proc.
Warning: Unsuitable for benchmarking (but still better than now), use monotimes.getMonoTime or cpuTime instead, depending on the use case.Source Edit proc format(dt: DateTime; f: string; loc: DateTimeLocale = DefaultLocale): string {. ...raises: [TimeFormatParseError], tags: [], forbids: [].}
-
Shorthand for constructing a TimeFormat and using it to format dt.
See Parsing and formatting dates for documentation of the format argument.
Example:
Source Editlet dt = dateTime(2000, mJan, 01, 00, 00, 00, 00, utc()) doAssert "2000-01-01" == format(dt, "yyyy-MM-dd")
proc format(dt: DateTime; f: TimeFormat; loc: DateTimeLocale = DefaultLocale): string {. ...raises: [], tags: [], forbids: [].}
-
Format dt using the format specified by f.
Example:
Source Editlet f = initTimeFormat("yyyy-MM-dd") let dt = dateTime(2000, mJan, 01, 00, 00, 00, 00, utc()) doAssert "2000-01-01" == dt.format(f)
-
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.
Example:
Source Editvar dt = dateTime(1970, mJan, 01, 00, 00, 00, 00, utc()) var tm = dt.toTime() doAssert format(tm, "yyyy-MM-dd'T'HH:mm:ss", utc()) == "1970-01-01T00:00:00"
proc fromUnixFloat(seconds: float): Time {....gcsafe, tags: [], raises: [], noSideEffect, ...forbids: [].}
-
Convert a unix timestamp in seconds to a Time; same as fromUnix but with subsecond resolution.
Example:
Source EditdoAssert fromUnixFloat(123456.0) == fromUnixFloat(123456) doAssert fromUnixFloat(-123456.0) == fromUnixFloat(-123456)
proc fromWinTime(win: int64): Time {....raises: [], tags: [], forbids: [].}
- Convert a Windows file time (100-nanosecond intervals since 1601-01-01T00:00:00Z) to a Time. Source Edit
proc getClockStr(dt = now()): string {....gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [], forbids: [].}
-
Gets the current local clock time as a string of the format HH:mm:ss.
Example:
Source Editecho getClockStr(now() - 1.hours)
proc getDateStr(dt = now()): string {....gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [], forbids: [].}
-
Gets the current local date as a string of the format YYYY-MM-dd.
Example:
Source Editecho getDateStr(now() - 1.months)
proc getDayOfWeek(monthday: MonthdayRange; month: Month; year: int): WeekDay {. ...tags: [], raises: [], gcsafe, forbids: [].}
-
Returns the day of the week enum from day, month and year. Equivalent with dateTime(year, month, monthday, 0, 0, 0, 0).weekday.
Example:
Source EditdoAssert getDayOfWeek(13, mJun, 1990) == dWed doAssert $getDayOfWeek(13, mJun, 1990) == "Wednesday"
proc getDayOfYear(monthday: MonthdayRange; month: Month; year: int): YeardayRange {. ...tags: [], raises: [], gcsafe, forbids: [].}
-
Returns the day of the year. Equivalent with dateTime(year, month, monthday, 0, 0, 0, 0).yearday.
Example:
Source EditdoAssert getDayOfYear(1, mJan, 2000) == 0 doAssert getDayOfYear(10, mJan, 2000) == 9 doAssert getDayOfYear(10, mFeb, 2000) == 40
proc getDaysInYear(year: int): int {....raises: [], tags: [], forbids: [].}
-
Get the number of days in a year
Example:
Source EditdoAssert getDaysInYear(2000) == 366 doAssert getDaysInYear(2001) == 365
proc getIsoWeekAndYear(dt: DateTime): tuple[isoweek: IsoWeekRange, isoyear: IsoYear] {....raises: [], tags: [], forbids: [].}
-
Returns the ISO 8601 week and year.Warning: The ISO week-based year can correspond to the following or previous year from 29 December to January 3.
Example:
Source Editassert getIsoWeekAndYear(initDateTime(21, mApr, 2018, 00, 00, 00)) == (isoweek: 16.IsoWeekRange, isoyear: 2018.IsoYear) block: let (w, y) = getIsoWeekAndYear(initDateTime(30, mDec, 2019, 00, 00, 00)) assert w == 01.IsoWeekRange assert y == 2020.IsoYear assert getIsoWeekAndYear(initDateTime(13, mSep, 2020, 00, 00, 00)) == (isoweek: 37.IsoWeekRange, isoyear: 2020.IsoYear) block: let (w, y) = getIsoWeekAndYear(initDateTime(2, mJan, 2021, 00, 00, 00)) assert w.int > 52 assert w.int < 54 assert y.int mod 100 == 20
proc getTime(): Time {....tags: [TimeEffect], gcsafe, raises: [], forbids: [].}
- Gets the current time as a Time with up to nanosecond resolution. Source Edit
proc getWeeksInIsoYear(y: IsoYear): IsoWeekRange {....raises: [], tags: [], forbids: [].}
-
Returns the number of weeks in the specified ISO 8601 week-based year, which can be either 53 or 52.
Example:
Source Editassert getWeeksInIsoYear(IsoYear(2019)) == 52 assert getWeeksInIsoYear(IsoYear(2020)) == 53
proc hours(h: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
-
TimeInterval of h hours.
echo getTime() + 2.hours
Source Edit proc initDateTime(monthday: MonthdayRange; month: Month; year: int; hour: HourRange; minute: MinuteRange; second: SecondRange; nanosecond: NanosecondRange; zone: Timezone = local()): DateTime {. ...deprecated: "use `dateTime`", raises: [], tags: [], forbids: [].}
-
DateTime in the specified timezone.
Example: cmd: --warning:deprecated:off
Source Editassert $initDateTime(30, mMar, 2017, 00, 00, 00, 00, utc()) == "2017-03-30T00:00:00Z"
Create a new proc initDateTime(monthday: MonthdayRange; month: Month; year: int; hour: HourRange; minute: MinuteRange; second: SecondRange; zone: Timezone = local()): DateTime {. ...deprecated: "use `dateTime`", raises: [], tags: [], forbids: [].}
-
DateTime in the specified timezone.
Example: cmd: --warning:deprecated:off
Source Editassert $initDateTime(30, mMar, 2017, 00, 00, 00, utc()) == "2017-03-30T00:00:00Z"
Create a new proc initDateTime(weekday: WeekDay; isoweek: IsoWeekRange; isoyear: IsoYear; hour: HourRange; minute: MinuteRange; second: SecondRange; nanosecond: NanosecondRange; zone: Timezone = local()): DateTime {. ...gcsafe, raises: [], tags: [], forbids: [].}
- Source Edit
proc initDateTime(weekday: WeekDay; isoweek: IsoWeekRange; isoyear: IsoYear; hour: HourRange; minute: MinuteRange; second: SecondRange; zone: Timezone = local()): DateTime {....gcsafe, raises: [], tags: [], forbids: [].}
- Source Edit
proc initDuration(nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, weeks: int64 = 0): Duration {....raises: [], tags: [], forbids: [].}
-
Create a new Duration.
Example:
Source Editlet dur = initDuration(seconds = 1, milliseconds = 1) doAssert dur.inMilliseconds == 1001 doAssert dur.inSeconds == 1
proc initTimeFormat(format: string): TimeFormat {. ...raises: [TimeFormatParseError], tags: [], forbids: [].}
-
Construct a new time format for parsing & formatting time types.
See Parsing and formatting dates for documentation of the format argument.
Example:
Source Editlet f = initTimeFormat("yyyy-MM-dd") doAssert "2000-01-01" == "2000-01-01".parse(f).format(f)
proc initTimeInterval(nanoseconds = 0; microseconds = 0; milliseconds = 0; seconds = 0; minutes = 0; hours = 0; days = 0; weeks = 0; months = 0; years = 0): TimeInterval {....raises: [], tags: [], forbids: [].}
-
Creates a new TimeInterval.
This proc doesn't perform any normalization! For example, initTimeInterval(hours = 24) and initTimeInterval(days = 1) are not equal.
You can also use the convenience procedures called milliseconds, seconds, minutes, hours, days, months, and years.
Example:
Source Editlet day = initTimeInterval(hours = 24) let dt = dateTime(2000, mJan, 01, 12, 00, 00, 00, utc()) doAssert $(dt + day) == "2000-01-02T12:00:00Z" doAssert initTimeInterval(hours = 24) != initTimeInterval(days = 1)
proc inMicroseconds(dur: Duration): int64 {....raises: [], tags: [], forbids: [].}
-
Converts the duration to the number of whole microseconds.
Example:
Source Editlet dur = initDuration(seconds = -2) doAssert dur.inMicroseconds == -2000000
proc inMilliseconds(dur: Duration): int64 {....raises: [], tags: [], forbids: [].}
-
Converts the duration to the number of whole milliseconds.
Example:
Source Editlet dur = initDuration(seconds = -2) doAssert dur.inMilliseconds == -2000
proc inNanoseconds(dur: Duration): int64 {....raises: [], tags: [], forbids: [].}
-
Converts the duration to the number of whole nanoseconds.
Example:
Source Editlet dur = initDuration(seconds = -2) doAssert dur.inNanoseconds == -2000000000
proc isInitialized(dt: DateTime): bool {....raises: [], tags: [], forbids: [].}
-
Example:
Source EditdoAssert now().isInitialized doAssert not default(DateTime).isInitialized
-
Returns whether t is a leap day, i.e. Feb 29 in a leap year. This matters as it affects time offset calculations.
Example:
Source Editlet dt = dateTime(2020, mFeb, 29, 00, 00, 00, 00, utc()) doAssert dt.isLeapDay doAssert dt+1.years-1.years != dt let dt2 = dateTime(2020, mFeb, 28, 00, 00, 00, 00, utc()) doAssert not dt2.isLeapDay doAssert dt2+1.years-1.years == dt2 doAssertRaises(Exception): discard dateTime(2021, mFeb, 29, 00, 00, 00, 00, utc())
proc isLeapYear(year: int): bool {....raises: [], tags: [], forbids: [].}
-
Returns true if year is a leap year.
Example:
Source EditdoAssert isLeapYear(2000) doAssert not isLeapYear(1900)
-
Get the Timezone implementation for the local timezone.
Example:
Source EditdoAssert now().timezone == local() doAssert local().name == "LOCAL"
proc microseconds(micros: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
- TimeInterval of micros microseconds. Source Edit
proc milliseconds(ms: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
- TimeInterval of ms milliseconds. Source Edit
proc minute(dt: DateTime): MinuteRange {.inline, ...raises: [], tags: [], forbids: [].}
- The number of minutes after the hour, in the range 0 to 59. Source Edit
proc minute=(dt: var DateTime; value: MinuteRange) {. ...deprecated: "Deprecated since v1.3.1", raises: [], tags: [], forbids: [].}
- Source Edit
proc minutes(m: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
-
TimeInterval of m minutes.
echo getTime() + 5.minutes
Source Edit proc monthday(dt: DateTime): MonthdayRange {.inline, ...raises: [], tags: [], forbids: [].}
- The day of the month, in the range 1 to 31. Source Edit
proc monthdayZero=(dt: var DateTime; value: int) {. ...deprecated: "Deprecated since v1.3.1", raises: [], tags: [], forbids: [].}
- Source Edit
proc months(m: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
-
TimeInterval of m months.
echo getTime() + 2.months
Source Edit proc monthZero=(dt: var DateTime; value: int) {. ...deprecated: "Deprecated since v1.3.1", raises: [], tags: [], forbids: [].}
- Source Edit
-
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 system's local timezone.
See also: https://en.wikipedia.org/wiki/Tz_database
Source Edit proc nanosecond(dt: DateTime): NanosecondRange {.inline, ...raises: [], tags: [], forbids: [].}
- The number of nanoseconds after the second, in the range 0 to 999_999_999. Source Edit
proc nanosecond(time: Time): NanosecondRange {....raises: [], tags: [], forbids: [].}
- Get the fractional part of a Time as the number of nanoseconds of the second. Source Edit
proc nanosecond=(dt: var DateTime; value: NanosecondRange) {. ...deprecated: "Deprecated since v1.3.1", raises: [], tags: [], forbids: [].}
- Source Edit
proc nanoseconds(nanos: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
- TimeInterval of nanos nanoseconds. Source Edit
-
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!
Example:
Source Editproc utcTzInfo(time: Time): ZonedTime = ZonedTime(utcOffset: 0, isDst: false, time: time) let utc = newTimezone("Etc/UTC", utcTzInfo, utcTzInfo)
proc now(): DateTime {....tags: [TimeEffect], gcsafe, raises: [], forbids: [].}
-
Get the current time as a DateTime in the local timezone. Shorthand for getTime().local.Warning: Unsuitable for benchmarking, use monotimes.getMonoTime or cpuTime instead, depending on the use case.Source Edit
proc parse(input, f: string; tz: Timezone = local(); loc: DateTimeLocale = DefaultLocale): DateTime {. ...raises: [TimeParseError, TimeFormatParseError], tags: [TimeEffect], forbids: [].}
-
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.
Example:
Source Editlet dt = dateTime(2000, mJan, 01, 00, 00, 00, 00, utc()) doAssert dt == parse("2000-01-01", "yyyy-MM-dd", utc())
proc parse(input: string; f: static[string]; zone: Timezone = local(); loc: DateTimeLocale = DefaultLocale): DateTime {. ...raises: [TimeParseError].}
- Overload that validates f at compile time. Source Edit
proc parse(input: string; f: TimeFormat; zone: Timezone = local(); loc: DateTimeLocale = DefaultLocale): DateTime {. ...raises: [TimeParseError], tags: [TimeEffect], forbids: [].}
-
Parses 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.
Month and day names from the passed in loc are used.
Example:
Source Editlet f = initTimeFormat("yyyy-MM-dd") let dt = dateTime(2000, mJan, 01, 00, 00, 00, 00, utc()) doAssert dt == "2000-01-01".parse(f, utc())
proc parseTime(input, f: string; zone: Timezone): Time {. ...raises: [TimeParseError, TimeFormatParseError], tags: [TimeEffect], forbids: [].}
-
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.
Example:
Source Editlet tStr = "1970-01-01T00:00:00+00:00" doAssert parseTime(tStr, "yyyy-MM-dd'T'HH:mm:sszzz", utc()) == fromUnix(0)
proc second(dt: DateTime): SecondRange {.inline, ...raises: [], tags: [], forbids: [].}
- The number of seconds after the minute, in the range 0 to 59. Source Edit
proc second=(dt: var DateTime; value: SecondRange) {. ...deprecated: "Deprecated since v1.3.1", raises: [], tags: [], forbids: [].}
- Source Edit
proc seconds(s: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
-
TimeInterval of s seconds.
echo getTime() + 5.seconds
Source Edit proc toParts(dur: Duration): DurationParts {....raises: [], tags: [], forbids: [].}
-
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.
Example:
Source Editvar dp = toParts(initDuration(weeks = 2, days = 1)) doAssert dp[Days] == 1 doAssert dp[Weeks] == 2 doAssert dp[Minutes] == 0 dp = toParts(initDuration(days = -1)) doAssert dp[Days] == -1
proc toParts(ti: TimeInterval): TimeIntervalParts {....raises: [], tags: [], forbids: [].}
-
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
Example:
Source Editvar tp = toParts(initTimeInterval(years = 1, nanoseconds = 123)) doAssert tp[Years] == 1 doAssert tp[Nanoseconds] == 123
proc toUnixFloat(t: Time): float {....gcsafe, tags: [], raises: [], forbids: [].}
-
Same as toUnix but using subsecond resolution.
Example:
Source Editlet t = getTime() # `<` because of rounding errors doAssert abs(t.toUnixFloat().fromUnixFloat - t) < initDuration(nanoseconds = 1000)
-
Get the Timezone implementation for the UTC timezone.
Example:
Source EditdoAssert now().utc.timezone == utc() doAssert utc().name == "Etc/UTC"
proc utcOffset=(dt: var DateTime; value: int) {. ...deprecated: "Deprecated since v1.3.1", raises: [], tags: [], forbids: [].}
- Source Edit
proc weeks(w: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
-
TimeInterval of w weeks.
echo getTime() + 2.weeks
Source Edit proc yearday(dt: DateTime): YeardayRange {.inline, ...raises: [], tags: [], forbids: [].}
- The number of days since January 1, in the range 0 to 365. Source Edit
proc yearday=(dt: var DateTime; value: YeardayRange) {. ...deprecated: "Deprecated since v1.3.1", raises: [], tags: [], forbids: [].}
- Source Edit
proc years(y: int): TimeInterval {.inline, ...raises: [], tags: [], forbids: [].}
-
TimeInterval of y years.
echo getTime() + 2.years
Source Edit proc zonedTimeFromAdjTime(zone: Timezone; adjTime: Time): ZonedTime {. ...raises: [], tags: [], forbids: [].}
-
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.
Source Edit