encode-extended-time

Arguments: second minute hour date month year &optional time-zone

This extension of encode-universal-time accepts years prior to 1900 and may (therefore) return negative numbers. When the year is 1900 or later, the value returned is the same as that returned by encode-universal-time.

Handling of two digit years

encode-universal-time treats two-digit years (like 04 or 99 or 55 -- one digit years are considered two digit years with the first digit 0) as the year ending in those digits nearest the current year (see encode-universal-time for the exact formula). In 2015, year 4 means 2004, year 99 means 1999, and year 55 means 2055. In 2050, 4 still means 2004, 55 still means 2055, but 99 means 2099.

encode-extended-time accepts any year, including one and two digit years from 0 to 99 (and from -99 to -1 but those are not legal year values for encode-universal-time). Therefore, one or two digit years are taken as absolute years, not relative to the current year.

Year 0 and calendar type

The standard calendar has positive years (referred to as Common Era or CE years) and negative years (refered to as Before Common Era or BCE years) but no year 0. Extended time allows for a year 0, and so you must subtract 1 from any non-positive year to get the correct BCE value. It also assumes that the Gregorian calandar extends back forever. (The Gregorian calendar is the modern calendar used more or less throughout the world, though many places also use other calendars, particularly when calculating religious dates.) In fact, it was adopted in 1582 CE and so dates prior to that year will not necessarily correspond to the dates found in documents and inscriptions prior to 1582 CE.

;; For values in the universal time range (after midnight, January 1, 
;; 1900 GMT) ENCODE-UNIVERSAL-TIME and ENCODE-EXTENDED-TIME return 
;; the same values so long as a 4 (or more) digit year is specified:
cg-user(35): (encode-universal-time 0 0 10 15 4 2015 8)
3638109600
cg-user(36): (encode-extended-time 0 0 10 15 4 2015 8)
3638109600

;; For values outside the universal time range, ENCODE-UNIVERSAL-TIME 
;; errors and ENCODE-EXTENDED-TIME returns a negative value:
cg-user(37): (encode-universal-time 0 0 10 15 4 1850 8)
Error: Illegal year: 1850.
[condition type: simple-error]
cg-user(38): (encode-extended-time 0 0 10 15 4 1850 8)
-1568786400

;; For two digit years, ENCODE-UNIVERSAL-TIME returns the value for
;; a year within 50 years of the current year, while
;; ENCODE-EXTENDED-TIME assumes the actual two-digit year and so
;; returns a negative value:
cg-user(39): (encode-universal-time 0 0 10 15 4 15 8)
3638109600
cg-user(40): (encode-extended-time 0 0 10 15 4 15 8)
-59475794400

;; ENCODE-EXTENDED-TIME accepts negative year. This is for 10:00 AM
;; March 15, 44 BCE. The ides of March. Caesar is being or is about
;; to be assassinated in Rome. (But see note in example on the
;; DECODE-EXTENDED-time page.)
cg-user(41): (encode-extended-time 0 0 10 15 3 -43 -1)
-61308802800
cg-user(42): 

See also decode-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.