decode-extended-time

Arguments: time &optional time-zone

Like the related decode-universal-time, this function returns nine values representing the clock time, day, month, and year, whether daylight saving time is in effect, and the time zone. Specifically, this function returns the following as multiple values:

1. The clock second: from 0 to 59.
2. The clock minute: for 0 to 59.
3. The clock hour: in 24-hour time, midnight being 0.
4. The day of the month: a value from 1 to 31.
5. The month: January is 1 and December is 12.
6. The year
7. The weekday: an integer from 0 to 6 indicating the day of the week, Monday being 0 and Sunday being 6.
8. Daylight saving time: a boolean indicating whether DST is or is not in effect.
9. The time zone: the current time zone will be used if the time-zone optional argument is not specified. Otherwise time-zone will be used.

time should be an integer. If time is non-negative, this function is the same as decode-universal-time. If time is negative, this function assume the value is a number of seconds prior to midnight, January 1, 1900 GMT and returns the time, date and year. Even negative years (those prior to 1 CE) are returned for sufficiently large negative times.

Note that for year prior to 1 CE, there is a year 0 even though the standard calendar does not have a year 0, so any non-positive year must be dimished by 1 to get the BCE equivalent. Further, this function assumes that the Gregorian Calendar (introduced in 1582 CE and not adopted more or less worldwide until the twentieth century) is in effect everywhere and for all time. That means that dates and times from inscriptions and historic documents, when entered, will not be to the second the instant a historic event likely happened (see the examples).

;; For positive time arguments, this function and
;; DECODE-UNIVERSAL-TIME are the same:
cg-user(22): (get-universal-time)
3638637699
cg-user(23): (decode-universal-time 3638637699)
39
41
13
21
4
2015
1
t
8
cg-user(24): (decode-extended-time 3638637699)
39
41
13
21
4
2015
1
t
8
cg-user(25): 

;; For negative times, DECODE-UNIVERSAL-TIME will signal an error
;; but DECODE-EXTENDED-TIME works:
;;
cg-user(14): (encode-extended-time 0 0 10 15 3 -43 -1)
-61308802800
cg-user(15): (decode-extended-time * -1)
0
0
10
15
3
-43
4
nil
-1
;; That is 10:00 AM, March 15, 44 BCE (remember, subtract 1 from
;; non-positive years to get the BCE year) in timezone -1 (Rome, Italy).
;; The Ides of March 44 BCE, when Julius Caesar was assassinated in the
;; Theater of Pompey in Rome (according to many historical accounts).
;; Assuming 10:00 AM is correct, did that happen 61308802800 seconds
;; before midnight, January 1, 1900 GMT? Likely not, even if the descriptions
;; from history books are accurate about the day and time, because
;; calendar changes from that time to now means that dates that far back 
;; are likely some number of days off. But the answer is quite close.

See also encode-extended-time, string-to-universal-time, and universal-time-to-string.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page is new in the 10.0 release.
Created 2019.8.20.