Module times

Search:
Group by:

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)

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.

PatternDescriptionExample
dNumeric value representing the day of the month, it will be either one or two digits long.

1/04/2012 -> 1
21/04/2012 -> 21

ddSame as above, but is 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 1-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, ranging from 0-23.

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.

5pm -> P
2am -> A

ttSame as above, but AM and PM instead of A and P respectively.

5pm -> PM
2am -> AM

yyThe last two digits of the year. When parsing, the current century is assumed.

2012 AD -> 12

yyyyThe 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.

2012 AD -> 2012
24 AD -> 0024
24 BC -> 00024
12345 AD -> +12345

YYYYThe year without any padding. Is always positive, even when the year is BC.

2012 AD -> 2012
24 AD -> 24
24 BC -> 24
12345 AD -> 12345

uuuuThe 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.

2012 AD -> 2012
24 AD -> 0024
24 BC -> -0023
12345 AD -> +12345

UUUUThe year without any padding. Will be negative when the year is BC.

2012 AD -> 2012
24 AD -> 24
24 BC -> -23
12345 AD -> 12345

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

zzzzSame as above but with :ss where ss represents seconds.

GMT+7 -> +07:00:00
GMT-5 -> -05:00:00

gEra: AD or BC

300 AD -> AD
300 BC -> BC

fffMilliseconds display

1000000 nanoseconds -> 1

ffffffMicroseconds display

1000000 nanoseconds -> 1000

fffffffffNanoseconds display

1000000 nanoseconds -> 1000000

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).

Types

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
WeekDay = enum
  dMon = "Monday", dTue = "Tuesday", dWed = "Wednesday", dThu = "Thursday", dFri = "Friday",
  dSat = "Saturday", dSun = "Sunday"
Represents a weekday.   Source Edit
MonthdayRange = range[1 .. 31]
  Source Edit
HourRange = range[0 .. 23]
  Source Edit
MinuteRange = range[0 .. 59]
  Source Edit
SecondRange = range[0 .. 60]
  Source Edit
YeardayRange = range[0 .. 365]
  Source Edit
NanosecondRange = range[0 .. 999999999]
  Source Edit
Time = object
  seconds: int64
  nanosecond: NanosecondRange
Represents a point in time.   Source Edit
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``).
  
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
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. 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.   Source Edit
Duration = object
  seconds: int64
  nanosecond: NanosecondRange
Represents a fixed duration of time. Uses the same time resolution as Time. This type should be prefered over TimeInterval unless non-static time units is needed.   Source Edit
TimeUnit = enum
  Nanoseconds, Microseconds, Milliseconds, Seconds, Minutes, Hours, Days, Weeks, Months,
  Years
Different units of time.   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
Timezone = ref object
  zonedTimeFromTimeImpl: proc (x: Time): ZonedTime {...}{.tags: [], raises: [], gcsafe,
      locks: 0.}
  zonedTimeFromAdjTimeImpl: proc (x: Time): ZonedTime {...}{.tags: [], raises: [], gcsafe,
      locks: 0.}
  name: string
Timezone interface for supporting DateTime's of arbritary timezones. The times module only supplies implementations for the systems local time and UTC.   Source Edit
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.
  
Represents a point in time with an associated UTC offset and DST flag. This type is only used for implementing timezones.   Source Edit
DurationParts = array[FixedTimeUnit, int64]
  Source Edit
TimeIntervalParts = array[TimeUnit, int]
  Source Edit
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: string
Represents a format for parsing and printing time types.   Source Edit

Consts

DurationZero = (seconds: 0, nanosecond: 0)
Zero value for durations. Useful for comparisons.
doAssert initDuration(seconds = 1) > DurationZero
doAssert initDuration(seconds = 0) == DurationZero
  Source Edit

Procs

proc convert[T: SomeInteger](unitFrom, unitTo: FixedTimeUnit; quantity: T): T {...}{.inline.}
Convert a quantity of some duration unit to another duration unit.

Examples:

doAssert convert(Days, Hours, 2) == 48
doAssert convert(Days, Weeks, 13) == 1
doAssert convert(Seconds, Milliseconds, -1) == -1000
  Source Edit
proc nanosecond(time: Time): NanosecondRange {...}{.raises: [], tags: [].}
Get the fractional part of a Time as the number of nanoseconds of the second.   Source Edit
proc weeks(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}
Number of whole weeks represented by the duration.   Source Edit
proc days(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}
Number of whole days represented by the duration.   Source Edit
proc minutes(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}
Number of whole minutes represented by the duration.   Source Edit
proc hours(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}
Number of whole hours represented by the duration.   Source Edit
proc seconds(dur: Duration): int64 {...}{.inline, raises: [], tags: [].}
Number of whole seconds represented by the duration.   Source Edit
proc milliseconds(dur: Duration): int {...}{.inline, raises: [], tags: [].}
Number of whole milliseconds represented by the fractional part of the duration.

Examples:

let dur = initDuration(seconds = 1, milliseconds = 1)
doAssert dur.milliseconds == 1
  Source Edit
proc microseconds(dur: Duration): int {...}{.inline, raises: [], tags: [].}
Number of whole microseconds represented by the fractional part of the duration.

Examples:

let dur = initDuration(seconds = 1, microseconds = 1)
doAssert dur.microseconds == 1
  Source Edit
proc nanoseconds(dur: Duration): int {...}{.inline, raises: [], tags: [].}
Number of whole nanoseconds represented by the fractional part of the duration.

Examples:

let dur = initDuration(seconds = 1, nanoseconds = 1)
doAssert dur.nanoseconds == 1
  Source Edit
proc fractional(dur: Duration): Duration {...}{.inline, raises: [], tags: [].}
The fractional part of duration, as a duration.

Examples:

let dur = initDuration(seconds = 1, nanoseconds = 5)
doAssert dur.fractional == initDuration(nanoseconds = 5)
  Source Edit
proc fromUnix(unix: int64): Time {...}{.gcsafe, locks: 0, tags: [], raises: [], noSideEffect.}
Convert a unix timestamp (seconds since 1970-01-01T00:00:00Z) to a Time.

Examples:

doAssert $fromUnix(0).utc == "1970-01-01T00:00:00Z"
  Source Edit
proc toUnix(t: Time): int64 {...}{.gcsafe, locks: 0, tags: [], raises: [], noSideEffect.}
Convert t to a unix timestamp (seconds since 1970-01-01T00:00:00Z).

Examples:

doAssert fromUnix(0).toUnix() == 0
  Source Edit
proc fromWinTime(win: int64): Time {...}{.raises: [], tags: [].}
Convert a Windows file time (100-nanosecond intervals since 1601-01-01T00:00:00Z) to a Time.   Source Edit
proc toWinTime(t: Time): int64 {...}{.raises: [], tags: [].}
Convert t to a Windows file time (100-nanosecond intervals since 1601-01-01T00:00:00Z).   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 getDayOfYear(monthday: MonthdayRange; month: Month; year: int): YeardayRange {...}{.
    tags: [], raises: [], gcsafe, locks: 0.}
Returns the day of the year. Equivalent with initDateTime(monthday, month, year, 0, 0, 0).yearday.   Source Edit
proc getDayOfWeek(monthday: MonthdayRange; month: Month; year: int): WeekDay {...}{.tags: [],
    raises: [], gcsafe, locks: 0.}
Returns the day of the week enum from day, month and year. Equivalent with initDateTime(monthday, month, year, 0, 0, 0).weekday.   Source Edit
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
  Source Edit
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
  Source Edit
proc `$`(dur: Duration): string {...}{.raises: [], tags: [].}
Human friendly string representation of 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"
  Source Edit
proc `+`(a, b: Duration): Duration {...}{.raises: [], tags: [].}
Add two durations together.

Examples:

doAssert initDuration(seconds = 1) + initDuration(days = 1) ==
    initDuration(seconds = 1, days = 1)
  Source Edit
proc `-`(a, b: Duration): Duration {...}{.raises: [], tags: [].}
Subtract a duration from another.

Examples:

doAssert initDuration(seconds = 1, days = 1) - initDuration(seconds = 1) ==
    initDuration(days = 1)
  Source Edit
proc `-`(a: Duration): Duration {...}{.raises: [], tags: [].}
Reverse a duration.

Examples:

doAssert -initDuration(seconds = 1) == initDuration(seconds = -1)
  Source Edit
proc `<`(a, b: Duration): bool {...}{.raises: [], tags: [].}
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.

Examples:

doAssert initDuration(seconds = 1) < initDuration(seconds = 2)
doAssert initDuration(seconds = -2) < initDuration(seconds = 1)
  Source Edit
proc `<=`(a, b: Duration): bool {...}{.raises: [], tags: [].}
  Source Edit
proc `==`(a, b: Duration): bool {...}{.raises: [], tags: [].}
  Source Edit
proc `*`(a: int64; b: Duration): Duration {...}{.raises: [], tags: [].}
Multiply a duration by some scalar.

Examples:

doAssert 5 * initDuration(seconds = 1) == initDuration(seconds = 5)
  Source Edit
proc `*`(a: Duration; b: int64): Duration {...}{.raises: [], tags: [].}
Multiply a duration by some scalar.

Examples:

doAssert initDuration(seconds = 1) * 5 == initDuration(seconds = 5)
  Source Edit
proc `div`(a: Duration; b: int64): Duration {...}{.raises: [], tags: [].}
Integer division for durations.

Examples:

doAssert initDuration(seconds = 3) div 2 == initDuration(milliseconds = 1500)
doAssert initDuration(nanoseconds = 3) div 2 == initDuration(nanoseconds = 1)
  Source Edit
proc initTime(unix: int64; nanosecond: NanosecondRange): Time {...}{.tags: [], raises: [],
    gcsafe, locks: 0, noSideEffect.}
Create a Time from a unix timestamp and a nanosecond part.   Source Edit
proc `-`(a, b: Time): Duration {...}{.extern: "ntDiffTime", raises: [], tags: [].}
Computes the duration between two points in time.   Source Edit
proc `+`(a: Time; b: Duration): Time {...}{.extern: "ntAddTime", raises: [], tags: [].}
Add a duration of time to a Time.

Examples:

doAssert (fromUnix(0) + initDuration(seconds = 1)) == fromUnix(1)
  Source Edit
proc `-`(a: Time; b: Duration): Time {...}{.extern: "ntSubTime", raises: [], tags: [].}
Subtracts a duration of time from a Time.

Examples:

doAssert (fromUnix(0) - initDuration(seconds = 1)) == fromUnix(-1)
  Source Edit
proc `<`(a, b: Time): bool {...}{.extern: "ntLtTime", raises: [], tags: [].}
Returns true iff a < b, that is iff a happened before b.   Source Edit
proc `<=`(a, b: Time): bool {...}{.extern: "ntLeTime", raises: [], tags: [].}
Returns true iff a <= b.   Source Edit
proc `==`(a, b: Time): bool {...}{.extern: "ntEqTime", raises: [], tags: [].}
Returns true if a == b, that is if both times represent the same point in time.   Source Edit
proc high(typ: typedesc[Time]): Time
  Source Edit
proc low(typ: typedesc[Time]): Time
  Source Edit
proc high(typ: typedesc[Duration]): Duration
Get the longest representable duration.   Source Edit
proc low(typ: typedesc[Duration]): Duration
Get the longest representable duration of negative direction.   Source Edit
proc abs(a: Duration): Duration {...}{.raises: [], tags: [].}

Examples:

doAssert initDuration(milliseconds = -1500).abs ==
    initDuration(milliseconds = 1500)
  Source Edit
proc toTime(dt: DateTime): Time {...}{.tags: [], raises: [], gcsafe, locks: 0.}
Converts a broken-down time structure to calendar time representation.   Source Edit
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)
  Source Edit
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.

See also: https://en.wikipedia.org/wiki/Tz_database

  Source Edit
proc zonedTimeFromTime(zone: Timezone; time: Time): ZonedTime {...}{.raises: [], tags: [].}
Returns the ZonedTime for some point in time.   Source Edit
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.

  Source Edit
proc `$`(zone: Timezone): string {...}{.raises: [], tags: [].}
Returns the name of the timezone.   Source Edit
proc `==`(zone1, zone2: Timezone): bool {...}{.raises: [], tags: [].}
Two Timezone's are considered equal if their name is equal.

Examples:

doAssert local() == local()
doAssert local() != utc()
  Source Edit
proc inZone(time: Time; zone: Timezone): DateTime {...}{.tags: [], raises: [], gcsafe, locks: 0.}
Convert time into a DateTime using zone as the timezone.   Source Edit
proc inZone(dt: DateTime; zone: Timezone): DateTime {...}{.tags: [], raises: [], gcsafe,
    locks: 0.}
Returns a DateTime representing the same point in time as dt but using zone as the timezone.   Source Edit
proc utc(): Timezone {...}{.raises: [], tags: [].}
Get the Timezone implementation for the UTC timezone.

Examples:

doAssert now().utc.timezone == utc()
doAssert utc().name == "Etc/UTC"
  Source Edit
proc local(): Timezone {...}{.raises: [], tags: [].}
Get the Timezone implementation for the local timezone.

Examples:

doAssert now().timezone == local()
doAssert local().name == "LOCAL"
  Source Edit
proc utc(dt: DateTime): DateTime {...}{.raises: [], tags: [].}
Shorthand for dt.inZone(utc()).   Source Edit
proc local(dt: DateTime): DateTime {...}{.raises: [], tags: [].}
Shorthand for dt.inZone(local()).   Source Edit
proc utc(t: Time): DateTime {...}{.raises: [], tags: [].}
Shorthand for t.inZone(utc()).   Source Edit
proc local(t: Time): DateTime {...}{.raises: [], tags: [].}
Shorthand for t.inZone(local()).   Source Edit
proc getTime(): Time {...}{.tags: [TimeEffect], gcsafe, locks: 0, raises: [].}
Gets the current time as a Time with nanosecond resolution.   Source Edit
proc now(): DateTime {...}{.tags: [TimeEffect], gcsafe, locks: 0, raises: [].}

Get the current time as a DateTime in the local timezone.

Shorthand for getTime().local.

  Source Edit
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"
  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

Examples:

let day = -initTimeInterval(hours = 24)
doAssert day.hours == -24
  Source Edit
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)
  Source Edit
proc getDateStr(): string {...}{.gcsafe, extern: "nt$1", tags: [TimeEffect], raises: [].}
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: [].}
Gets the current clock time as a string of the format HH:MM:SS.   Source Edit
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
  Source Edit
proc `$`(ti: TimeInterval): string {...}{.raises: [], tags: [].}
Get string representation of TimeInterval

Examples:

doAssert $initTimeInterval(years = 1, nanoseconds = 123) ==
    "1 year and 123 nanoseconds"
doAssert $initTimeInterval() == "0 nanoseconds"
  Source Edit
proc nanoseconds(nanos: int): TimeInterval {...}{.inline, raises: [], tags: [].}
TimeInterval of nanos nanoseconds.   Source Edit
proc microseconds(micros: int): TimeInterval {...}{.inline, raises: [], tags: [].}
TimeInterval of micros microseconds.   Source Edit
proc milliseconds(ms: int): TimeInterval {...}{.inline, raises: [], tags: [].}
TimeInterval of ms milliseconds.   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 weeks(w: int): TimeInterval {...}{.inline, raises: [], tags: [].}

TimeInterval of w weeks.

echo getTime() + 2.weeks

  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 initDateTime(monthday: MonthdayRange; month: Month; year: int; hour: HourRange;
                 minute: MinuteRange; second: SecondRange;
                 nanosecond: NanosecondRange; zone: Timezone = local()): DateTime {...}{.
    raises: [], tags: [].}
Create a new DateTime in the specified timezone.

Examples:

let dt1 = initDateTime(30, mMar, 2017, 0, 0, 0, 0, utc())
doAssert $dt1 == "2017-03-30T00:00:00Z"
  Source Edit
proc initDateTime(monthday: MonthdayRange; month: Month; year: int; hour: HourRange;
                 minute: MinuteRange; second: SecondRange; zone: Timezone = local()): DateTime {...}{.
    raises: [], tags: [].}
Create a new DateTime in the specified timezone.

Examples:

let dt1 = initDateTime(30, mMar, 2017, 0, 0, 0, utc())
doAssert $dt1 == "2017-03-30T00:00:00Z"
  Source Edit
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"
  Source Edit
proc `-`(dt: DateTime; interval: TimeInterval): DateTime {...}{.raises: [], tags: [].}
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.

Examples:

let dt = initDateTime(30, mMar, 2017, 0, 0, 0, utc())
doAssert $(dt - 5.days) == "2017-03-25T00:00:00Z"
  Source Edit
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"
  Source Edit
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"
  Source Edit
proc `-`(dt1, dt2: DateTime): Duration {...}{.raises: [], tags: [].}
Compute the duration between 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)
  Source Edit
proc `<`(a, b: DateTime): bool {...}{.raises: [], tags: [].}
Returns true iff a < b, that is iff a happened before b.   Source Edit
proc `<=`(a, b: DateTime): bool {...}{.raises: [], tags: [].}
Returns true iff a <= b.   Source Edit
proc `==`(a, b: DateTime): bool {...}{.raises: [], tags: [].}
Returns true if a == b, that is if both dates represent the same point in time.   Source Edit
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
  Source Edit
proc `+`(time: Time; interval: TimeInterval): Time {...}{.raises: [], tags: [].}
Adds interval to time. If interval contains any years, months, weeks or days the operation is performed in the local timezone.

Examples:

let tm = fromUnix(0)
doAssert tm + 5.seconds == fromUnix(5)
  Source Edit
proc `-`(time: Time; interval: TimeInterval): Time {...}{.raises: [], tags: [].}
Subtracts interval from Time time. If interval contains any years, months, weeks or days the operation is performed in the local timezone.

Examples:

let tm = fromUnix(5)
doAssert tm - 5.seconds == fromUnix(0)
  Source Edit
proc `+=`[T, U: TimesMutableTypes](a: var T; b: U)
Modify a in place by adding b.

Examples:

var tm = fromUnix(0)
tm += initDuration(seconds = 1)
doAssert tm == fromUnix(1)
  Source Edit
proc `-=`[T, U: TimesMutableTypes](a: var T; b: U)
Modify a in place by subtracting b.

Examples:

var tm = fromUnix(5)
tm -= initDuration(seconds = 5)
doAssert tm == fromUnix(0)
  Source Edit
proc `*=`[T: TimesMutableTypes; U](a: var T; b: U)

Examples:

var dur = initDuration(seconds = 1)
dur *= 5
doAssert dur == initDuration(seconds = 5)
  Source Edit
proc `$`(f: TimeFormat): string {...}{.raises: [], tags: [].}
Returns the format string that was used to construct f.

Examples:

let f = initTimeFormat("yyyy-MM-dd")
doAssert $f == "yyyy-MM-dd"
  Source Edit
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)
  Source Edit
proc format(dt: DateTime; f: TimeFormat): string {...}{.raises: [], tags: [].}
Format 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)
  Source Edit
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")
  Source Edit
proc format(dt: DateTime; f: static[string]): string {...}{.raises: [].}
Overload that validates format at compile time.   Source Edit
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"
  Source Edit
proc format(time: Time; f: static[string]; zone: Timezone = local()): string {...}{.tags: [].}
Overload that validates f at compile time.   Source Edit
proc parse(input: string; f: TimeFormat; zone: Timezone = local()): DateTime {...}{.
    raises: [ValueError, OverflowError, UnpackError], tags: [TimeEffect].}
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.

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())
  Source Edit
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())
  Source Edit
proc parse(input: string; f: static[string]; zone: Timezone = local()): DateTime
Overload that validates f at compile time.   Source Edit
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)
  Source Edit
proc parseTime(input: string; f: static[string]; zone: Timezone): Time
Overload that validates format at compile time.   Source Edit
proc `$`(dt: DateTime): string {...}{.tags: [], raises: [], gcsafe, locks: 0.}
Converts a DateTime object to a string representation. It uses the format 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"
  Source Edit
proc `$`(time: Time): string {...}{.tags: [], 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.

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")
  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 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
  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:

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
  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).

getTime should generally be prefered over this proc.

  Source Edit
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.

  Source Edit
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.

  Source Edit
proc initInterval(seconds, minutes, hours, days, months, years: int = 0): TimeInterval {...}{.
    deprecated, raises: [], tags: [].}
Deprecated since v0.18.0: use initTimeInterval instead.   Source Edit
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

  Source Edit
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

  Source Edit
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

  Source Edit
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

  Source Edit
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

  Source Edit
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).

  Source Edit
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.

  Source Edit
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.

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

Converts a Time to a TimeInterval.

Deprecated since v0.14.0: use toTimeInterval instead.

  Source Edit
proc getDayOfWeek(day, month, year: int): WeekDay {...}{.tags: [], raises: [], gcsafe, locks: 0,
    deprecated.}
Deprecated since v0.18.0: use getDayOfWeek(monthday: MonthdayRange; month: Month; year: int) instead.   Source Edit
proc getDayOfWeekJulian(day, month, year: int): WeekDay {...}{.deprecated, raises: [],
    tags: [].}
Returns the day of the week enum from day, month and year, according to the Julian calendar. Deprecated since v0.18.0   Source Edit
proc adjTime(zt: ZonedTime): Time {...}{.deprecated: "Use zt.time instead", raises: [],
                                tags: [].}
Deprecated since v0.19.0: use the time field instead.   Source Edit
proc adjTime=(zt: var ZonedTime; adjTime: Time) {...}{.deprecated: "Use zt.time instead",
    raises: [], tags: [].}
Deprecated since v0.19.0: use the time field instead.   Source Edit
proc zoneInfoFromUtc(zone: Timezone; time: Time): ZonedTime {...}{.
    deprecated: "Use zonedTimeFromTime instead", raises: [], tags: [].}
Deprecated since v0.19.0: use zonedTimeFromTime instead.   Source Edit
proc zoneInfoFromTz(zone: Timezone; adjTime: Time): ZonedTime {...}{.
    deprecated: "Use zonedTimeFromAdjTime instead", raises: [], tags: [].}
Deprecated since v0.19.0: use the zonedTimeFromAdjTime instead.   Source Edit