# Module times

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

# Imports

strutils

# Types

    TMonth* = enum
      mJan, mFeb, mMar, mApr, mMay, mJun, mJul, mAug, mSep, mOct, mNov, mDec

  represents a month

    TWeekDay* = enum
      dMon, dTue, dWed, dThu, dFri, dSat, dSun

  represents a weekday

    TTime* = distinct TTimeImpl

  distinct type that represents a time

    TTimeInfo* = object of TObject
      second*: range[0 .. 61]     ## The number of seconds after the minute,
                                  ## normally in the range 0 to 59, but can
                                  ## be up to 61 to allow for leap seconds.
      minute*: range[0 .. 59]     ## The number of minutes after the hour,
                                  ## in the range 0 to 59.
      hour*: range[0 .. 23]       ## The number of hours past midnight,
                                  ## in the range 0 to 23.
      monthday*: range[1 .. 31]   ## The day of the month, in the range 1 to 31.
      month*: TMonth              ## The current month.
      year*: range[- 10000 .. 10000] ## The current year.
      weekday*: TWeekDay          ## The current day of the week.
      yearday*: range[0 .. 365]   ## The number of days since January 1,
                                  ## in the range 0 to 365.
                                  ## Always 0 if the target is ECMAScript.
      isDST*: bool                ## Determines whether DST is in effect. Always
                                  ## ``False`` if time is UTC.
      tzname*: string             ## The timezone this time is in. E.g. GMT
      timezone*: int              ## The offset of the (non-DST) timezone in seconds
                                  ## west of UTC.

  represents a time in different parts

    TTimeInterval* {.pure.} = object
      miliseconds*: int           ## The number of miliseconds
      seconds*: int               ## The number of seconds
      minutes*: int               ## The number of minutes
      hours*: int                 ## The number of hours
      days*: int                  ## The number of days
      months*: int                ## The number of months
      years*: int                 ## The number of years

  a time interval

# Procs

    proc getTime*(): TTime

  gets the current calendar time

    proc getLocalTime*(t: TTime): TTimeInfo

  converts the calendar time t to broken-time representation, expressed relative to the user's specified time zone.

    proc getGMTime*(t: TTime): TTimeInfo

  converts the calendar time t to broken-down time representation, expressed in Coordinated Universal Time (UTC).

    proc TimeInfoToTime*(timeInfo: TTimeInfo): TTime

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

    proc `$`*(timeInfo: TTimeInfo): string

  converts a TTimeInfo object to a string representation.

    proc `$`*(time: TTime): string

  converts a calendar time to a string representation.

    proc `-`*(a, b: TTime): int64 {.rtl, extern: "ntDiffTime".}

  computes the difference of two calendar times. Result is in seconds.

    proc `<`*(a, b: TTime): bool {.rtl, extern: "ntLtTime".}

  returns true iff `a < b`, that is iff a happened before b.

    proc `<=`*(a, b: TTime): bool {.rtl, extern: "ntLeTime".}

  returns true iff `a <= b`.

    proc getTzname*(): tuple[nonDST, DST: string]

  returns the local timezone; `nonDST` is the name of the local non-DST timezone, `DST` is the name of the local DST timezone.

    proc getTimezone*(): int

  returns the offset of the local (non-DST) timezone in seconds west of UTC.

    proc getStartMilsecs*(): int {.deprecated.}

  get the miliseconds from the start of the program. Deprecated since version 0.8.10. Use `epochTime` or `cpuTime` instead.

    proc initInterval*(miliseconds, seconds, minutes, hours, days, months, years: int = 0): TTimeInterval

  creates a new `TTimeInterval`.

    proc `+`*(a: TTimeInfo; interval: TTimeInterval): TTimeInfo

  adds `interval` time.

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

    proc `-`*(a: TTimeInfo; interval: TTimeInterval): TTimeInfo

  subtracts `interval` time.

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

    proc epochTime*(): float {.rtl, extern: "nt$1".}

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

    proc cpuTime*(): float {.rtl, extern: "nt$1".}

  gets time spent that the CPU spent to run the current process in seconds. This may be more useful for benchmarking than `epochTime`. However, it may measure the real time instead (depending on the OS). The value of the result has no meaning. To generate useful timing values, take the difference between the results of two `cpuTime` calls:

      var t0 = cpuTime()
      doWork()
      echo "CPU time [s] ", cpuTime() - t0

    proc unixTimeToWinTime*(t: TTime): int64

  converts a UNIX TTime (`time_t`) to a Windows file time

    proc winTimeToUnixTime*(t: int64): TTime

  converts a Windows time to a UNIX TTime (`time_t`)

    proc getDateStr*(): string {.rtl, extern: "nt$1".}

  gets the current date as a string of the format `YYYY-MM-DD`.

    proc getClockStr*(): string {.rtl, extern: "nt$1".}

  gets the current clock time as a string of the format `HH:MM:SS`.

    proc `$`*(day: TWeekDay): string

  stingify operator for `TWeekDay`.

    proc `$`*(m: TMonth): string

  stingify operator for `TMonth`.

    proc format*(info: TTimeInfo; f: string): string

  This function formats info as specified by f. The following format specifiers are available:

  Specifier | Description | Example
  --- | --- | ---
  d | Numeric value of the day of the month, it will be one or two digits long. | `1/04/2012 -> 1`, `21/04/2012 -> 21`
  dd | Same as above, but always two digits. | `1/04/2012 -> 01`, `21/04/2012 -> 21`
  ddd | Three letter string which indicates the day of the week. | `Saturday -> Sat`, `Monday -> Mon`
  dddd | Full string for the day of the week. | `Saturday -> Saturday`, `Monday -> Monday`
  h | The hours in one digit if possible. Ranging from 0-12. | `5pm -> 5`, `2am -> 2`
  hh | The hours in two digits always. If the hour is one digit 0 is prepended. | `5pm -> 05`, `11am -> 11`
  H | The hours in one digit if possible, randing from 0-24. | `5pm -> 17`, `2am -> 2`
  HH | The hours in two digits always. 0 is prepended if the hour is one digit. | `5pm -> 17`, `2am -> 02`
  m | The minutes in 1 digit if possible. | `5:30 -> 30`, `2:01 -> 1`
  mm | Same as above but always 2 digits, 0 is prepended if the minute is one digit. | `5:30 -> 30`, `2:01 -> 01`
  M | The month in one digit if possible. | `September -> 9`, `December -> 12`
  MM | The month in two digits always. 0 is prepended. | `September -> 09`, `December -> 12`
  MMM | Abbreviated three-letter form of the month. | `September -> Sep`, `December -> Dec`
  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. | `00:00:06 -> 06`
  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. |
  y(yyyy) | This displays the year to different digits. You most likely only want 2 or 4 'y's |
  yy | Displays the year to two digits. | `2012 -> 12`
  yyyy | Displays the year to four digits. | `2012 -> 2012`
  z | Displays the timezone offset from UTC. | `GMT+7 -> +7`, `GMT-5 -> -5`
  zz | Same as above but with leading 0. | `GMT+7 -> +07`, `GMT-5 -> -05`
  zzz | Same as above but with `:00`. | `GMT+7 -> +07:00`, `GMT-5 -> -05:00`
  ZZZ | Displays the name of the timezone. | `GMT -> GMT`, `EST -> EST`

  Other strings can be inserted by putting them in `''`. For example `hh'->'mm` will give `01->56`.

Generated: 2012-09-23 21:47:54 UTC