4.5 time-date

While not really a part of the MIME library, it is convenient to document time conversion functions often used when parsing Date headers and manipulating time. (Not by using tesseracts, though, I’m sorry to say.)

These functions convert between five formats: A date string, a Lisp timestamp, a decoded time list, a second number, and a day number.

Here’s a bunch of time/date/second/day examples:

(parse-time-string "Sat Sep 12 12:21:54 1998 +0200")
⇒ (54 21 12 12 9 1998 6 -1 7200)

(time-convert
  (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
  'integer)
⇒ 905595714

(float-time '(905595714000000 . 1000000))
⇒ 905595714.0

(time-convert 905595714.0 1000000)
⇒ (905595714000000 . 1000000)

(time-to-days '(905595714000000 . 1000000))
⇒ 729644

(time-convert (days-to-time 729644) 'integer)
⇒ 63041241600

(time-convert (time-since '(905595714000000 . 1000000))
              1000000)
⇒ (631963244775642171 . 1000000000)

(time-less-p '(905595714000000 . 1000000)
             '(905595593000000000 . 1000000000))
⇒ nil

(time-equal-p '(905595593000000000 . 1000000000)
              '(905595593000000    . 1000000   ))
⇒ t

(time-subtract '(905595714000000 . 1000000)
               '(905595593000000000 . 1000000000))
⇒ (121000000 . 1000000)

(days-between "Sat Sep 12 12:21:54 1998 +0200"
              "Sat Sep 07 12:21:54 1998 +0200")
⇒ 5

(date-leap-year-p 2000)
⇒ t

(time-to-day-in-year '(905595714000000 . 1000000))
⇒ 255

(time-to-number-of-days
 (time-since
  (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
⇒ 6472.722661506652

And finally, we have safe-date-to-time, which does the same as date-to-time, but returns a zero time if the date is syntactically malformed.

The five data representations used are the following:

date

An RFC 822 (or similar) date string. For instance: "Sat Sep 12 12:21:54 1998 +0200".

time

A Lisp timestamp. For instance: (905595714000000 . 1000000).

seconds

An integer or floating point count of seconds. For instance: 905595714.0, 905595714.

days

An integer number representing the number of days since Sunday, December 31, 1 BC (Gregorian). For instance: 729644.

decoded time

A list of decoded time. For instance: (54 21 12 12 9 1998 6 nil 7200).

All the examples above represent the same moment, except that days represents the day containing the moment.

These are the functions available:

date-to-time

Take a date and return a time.

time-convert

Take a time and return a timestamp in a specified form.

float-time

Take a time and return seconds.

encode-time

Take a decoded time and return a timestamp.

time-to-days

Take a time and return days.

days-to-time

Take days and return a time.

date-to-day

Take a date and return days.

time-to-number-of-days

Take a time and return the number of days that represents.

safe-date-to-time

Take a date and return a time. If the date is not syntactically valid, return a “zero” time.

time-less-p

Take two times and say whether the first time is less (i.e., earlier) than the second time. (This is a built-in function.)

time-equal-p

Check whether two time values are equal. The time values need not be in the same format. (This is a built-in function.)

time-since

Take a time and return a time saying how long it was since that time.

time-subtract

Take two times and subtract the second from the first. I.e., return the time between the two times. (This is a built-in function.)

days-between

Take two days and return the number of days between those two days.

date-leap-year-p

Take a year number and say whether it’s a leap year.

time-to-day-in-year

Take a time and return the day number within the year that the time is in.