### 4.13 Time and Date ¶

If `(provided? 'current-time)`:

The procedures `current-time`, `difftime`, and `offset-time` deal with a calendar time datatype which may or may not be disjoint from other Scheme datatypes.

Function: current-time ¶

  Returns the time since 00:00:00 GMT, January 1, 1970, measured in seconds. Note that the reference time is different from the reference time for `get-universal-time` in Common-Lisp Time.

Function: difftime caltime1 caltime0 ¶

  Returns the difference (number of seconds) between twe calendar times: caltime1 - caltime0. caltime0 may also be a number.

Function: offset-time caltime offset ¶

  Returns the calendar time of caltime offset by offset number of seconds `(+ caltime offset)`.

#### 4.13.1 Time Zone ¶

(require ’time-zone)

Data Format: TZ-string ¶

  POSIX standards specify several formats for encoding time-zone rules.

  `:<pathname>`

    If the first character of <pathname> is ‘`/`’, then <pathname> specifies the absolute pathname of a tzfile(5) format time-zone file. Otherwise, <pathname> is interpreted as a pathname within tzfile:vicinity (/usr/lib/zoneinfo/) naming a tzfile(5) format time-zone file.

  `<std><offset>`

    The string <std> consists of 3 or more alphabetic characters. <offset> specifies the time difference from GMT. The <offset> is positive if the local time zone is west of the Prime Meridian and negative if it is east. <offset> can be the number of hours or hours and minutes (and optionally seconds) separated by ‘`:`’. For example, `-4:30`.

  `<std><offset><dst>`

    <dst> is the at least 3 alphabetic characters naming the local daylight-savings-time.

  `<std><offset><dst><doffset>`

    <doffset> specifies the offset from the Prime Meridian when daylight-savings-time is in effect.

  The non-tzfile formats can optionally be followed by transition times specifying the day and time when a zone changes from standard to daylight-savings and back again.

  `,<date>/<time>,<date>/<time>`

    The <time>s are specified like the <offset>s above, except that leading ‘`+`’ and ‘`-`’ are not allowed.

    Each <date> has one of the formats:

    `J<day>`

      specifies the Julian day with <day> between 1 and 365. February 29 is never counted and cannot be referenced.

    `<day>`

      This specifies the Julian day with n between 0 and 365. February 29 is counted in leap years and can be specified.

    `M<month>.<week>.<day>`

      This specifies day <day> (0 <= <day> <= 6) of week <week> (1 <= <week> <= 5) of month <month> (1 <= <month> <= 12). Week 1 is the first week in which day d occurs and week 5 is the last week in which day <day> occurs. Day 0 is a Sunday.

Data Type: time-zone ¶

  is a datatype encoding how many hours from Greenwich Mean Time the local time is, and the Daylight Savings Time rules for changing it.

Function: time-zone TZ-string ¶

  Creates and returns a time-zone object specified by the string TZ-string. If `time-zone` cannot interpret TZ-string, `#f` is returned.

Function: tz:params caltime tz ¶

  tz is a time-zone object. `tz:params` returns a list of three items:

  0. An integer. 0 if standard time is in effect for timezone tz at caltime; 1 if daylight savings time is in effect for timezone tz at caltime.
  1. The number of seconds west of the Prime Meridian timezone tz is at caltime.
  2. The name for timezone tz at caltime.

  `tz:params` is unaffected by the default timezone; inquiries can be made of any timezone at any calendar time.

Function: tz:std-offset tz ¶

  tz is a time-zone object. `tz:std-offset` returns the number of seconds west of the Prime Meridian timezone tz is.

The rest of these procedures and variables are provided for POSIX compatability. Because of shared state they are not thread-safe.

Function: tzset ¶

  Returns the default time-zone.

Function: tzset tz ¶

  Sets (and returns) the default time-zone to tz.

Function: tzset TZ-string ¶

  Sets (and returns) the default time-zone to that specified by TZ-string.

  `tzset` also sets the variables *timezone*, daylight?, and tzname. This function is automatically called by the time conversion procedures which depend on the time zone (see Time and Date).

Variable: *timezone* ¶

  Contains the difference, in seconds, between Greenwich Mean Time and local standard time (for example, in the U.S. Eastern time zone (EST), timezone is 5*60*60). `*timezone*` is initialized by `tzset`.

Variable: daylight? ¶

  is `#t` if the default timezone has rules for Daylight Savings Time. Note: daylight? does not tell you when Daylight Savings Time is in effect, just that the default zone sometimes has Daylight Savings Time.

Variable: tzname ¶

  is a vector of strings. Index 0 has the abbreviation for the standard timezone; If daylight?, then index 1 has the abbreviation for the Daylight Savings timezone.

#### 4.13.2 Posix Time ¶

    (require 'posix-time)

Data Type: Calendar-Time ¶

  is a datatype encapsulating time.

Data Type: Coordinated Universal Time ¶

  (abbreviated UTC) is a vector of integers representing time:

  0. seconds (0 - 61)
  1. minutes (0 - 59)
  2. hours since midnight (0 - 23)
  3. day of month (1 - 31)
  4. month (0 - 11). Note difference from `decode-universal-time`.
  5. the number of years since 1900. Note difference from `decode-universal-time`.
  6. day of week (0 - 6)
  7. day of year (0 - 365)
  8. 1 for daylight savings, 0 for regular time

Function: gmtime caltime ¶

  Converts the calendar time caltime to UTC and returns it.

Function: localtime caltime tz ¶

  Returns caltime converted to UTC relative to timezone tz.

Function: localtime caltime ¶

  converts the calendar time caltime to a vector of integers expressed relative to the user’s time zone. `localtime` sets the variable *timezone* with the difference between Coordinated Universal Time (UTC) and local standard time in seconds (see tzset).

Function: gmktime univtime ¶

  Converts a vector of integers in GMT Coordinated Universal Time (UTC) format to a calendar time.

Function: mktime univtime ¶

  Converts a vector of integers in local Coordinated Universal Time (UTC) format to a calendar time.

Function: mktime univtime tz ¶

  Converts a vector of integers in Coordinated Universal Time (UTC) format (relative to time-zone tz) to calendar time.

Function: asctime univtime ¶

  Converts the vector of integers caltime in Coordinated Universal Time (UTC) format into a string of the form `"Wed Jun 30 21:49:08 1993"`.

Function: gtime caltime ¶
Function: ctime caltime ¶
Function: ctime caltime tz ¶

  Equivalent to `(asctime (gmtime caltime))`, `(asctime (localtime caltime))`, and `(asctime (localtime caltime tz))`, respectively.

#### 4.13.3 Common-Lisp Time ¶

    (require 'common-lisp-time)

Function: get-decoded-time ¶

  Equivalent to `(decode-universal-time (get-universal-time))`.

Function: get-universal-time ¶

  Returns the current time as Universal Time, number of seconds since 00:00:00 Jan 1, 1900 GMT. Note that the reference time is different from `current-time`.

Function: decode-universal-time univtime ¶

  Converts univtime to Decoded Time format. Nine values are returned:

  0. seconds (0 - 61)
  1. minutes (0 - 59)
  2. hours since midnight
  3. day of month
  4. month (1 - 12). Note difference from `gmtime` and `localtime`.
  5. year (A.D.). Note difference from `gmtime` and `localtime`.
  6. day of week (0 - 6)
  7. #t for daylight savings, #f otherwise
  8. hours west of GMT (-24 - +24)

  Notice that the values returned by `decode-universal-time` do not match the arguments to `encode-universal-time`.

Function: encode-universal-time second minute hour date month year ¶
Function: encode-universal-time second minute hour date month year time-zone ¶

  Converts the arguments in Decoded Time format to Universal Time format. If time-zone is not specified, the returned time is adjusted for daylight saving time. Otherwise, no adjustment is performed.

  Notice that the values returned by `decode-universal-time` do not match the arguments to `encode-universal-time`.

#### 4.13.4 ISO 8601 ¶

`(require 'iso-8601)`

Function: time->iso-8601 time ¶

  time is the time in seconds since 00:00:00 GMT, January 1, 1970. `time->iso-8601` returns an expanded ISO 8601 format string for the date and time.

Function: time->iso8601 time ¶

  time is a time in seconds since 00:00:00 GMT, January 1, 1970. `time->iso8601` returns a compact ISO 8601 format string for the date and time.

Function: iso-8601->time str ¶

  str is a string in ISO 8601 format, either compact or expanded. `iso-8601->time` returns that time in seconds since 00:00:00 GMT, January 1, 1970.

#### 4.13.5 Time Infrastructure ¶

`(require 'time-core)`

Function: time:gmtime tm ¶
Function: time:invert decoder target ¶
Function: time:split t tm_isdst tm_gmtoff tm_zone ¶

`(require 'tzfile)`

Function: tzfile:read path ¶