Next: Time Parsing, Previous: Time Zone Rules, Up: System Interface [Contents][Index]

### 38.7 Time Conversion

These functions convert time values (see Time of Day) into calendrical information and vice versa.

Many 32-bit operating systems are limited to system times containing 32 bits of information in their seconds component; these systems typically handle only the times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 Universal Time. However, 64-bit and some 32-bit operating systems have larger seconds components, and can represent times far in the past or future.

Time conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers count the number of years since the year 1 B.C., and do not skip zero as traditional Gregorian years do; for example, the year number âˆ’37 represents the Gregorian year 38 B.C.

Function: decode-time &optional time zone

  This function converts a time value into calendrical information. If you don’t specify time, it decodes the current time, and similarly zone defaults to the current time zone rule. See Time Zone Rules. The return value is a list of nine elements, as follows:

      (seconds minutes hour day month year dow dst utcoff)

  Here is what the elements mean:

  seconds

    The number of seconds past the minute, as an integer between 0 and 59. On some operating systems, this is 60 for leap seconds.

  minutes

    The number of minutes past the hour, as an integer between 0 and 59.

  hour

    The hour of the day, as an integer between 0 and 23.

  day

    The day of the month, as an integer between 1 and 31.

  month

    The month of the year, as an integer between 1 and 12.

  year

    The year, an integer typically greater than 1900.

  dow

    The day of week, as an integer between 0 and 6, where 0 stands for Sunday.

  dst

    `t` if daylight saving time is effect, otherwise `nil`.

  utcoff

    An integer indicating the Universal Time offset in seconds, i.e., the number of seconds east of Greenwich.

  Common Lisp Note: Common Lisp has different meanings for dow and utcoff.

Function: encode-time seconds minutes hour day month year &optional zone

  This function is the inverse of `decode-time`. It converts seven items of calendrical data into a list-of-integer time value. For the meanings of the arguments, see the table above under `decode-time`.

  Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call `encode-time`.

  The optional argument zone defaults to the current time zone rule. See Time Zone Rules. In addition to the usual time zone rule values, it can also be a list (as you would get from `current-time-zone`) or an integer (as from `decode-time`), applied without any further alteration for daylight saving time.

  If you pass more than seven arguments to `encode-time`, the first six are used as seconds through year, the last argument is used as zone, and the arguments in between are ignored. This feature makes it possible to use the elements of a list returned by `decode-time` as the arguments to `encode-time`, like this:

      (apply 'encode-time (decode-time …))

  You can perform simple date arithmetic by using out-of-range values for the seconds, minutes, hour, day, and month arguments; for example, day 0 means the day preceding the given month.

  The operating system puts limits on the range of possible time values; if you try to encode a time that is out of range, an error results. For instance, years before 1970 do not work on some systems; on others, years as early as 1901 do work.

Next: Time Parsing, Previous: Time Zone Rules, Up: System Interface [Contents][Index]