4.5 time-date

While not really a part of the MIME library, it is convenient to document this library here. It deals with 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, an Emacs time structure, 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 nil 7200)
     
     (date-to-time "Sat Sep 12 12:21:54 1998 +0200")
     ⇒ (13818 19266)
     
     (time-to-seconds '(13818 19266))
     ⇒ 905595714.0
     
     (seconds-to-time 905595714.0)
     ⇒ (13818 19266 0 0)
     
     (time-to-days '(13818 19266))
     ⇒ 729644
     
     (days-to-time 729644)
     ⇒ (961933 512)
     
     (time-since '(13818 19266))
     ⇒ (6797 9607 984839 247000)
     
     (time-less-p '(13818 19266) '(13818 19145))
     ⇒ nil
     
     (subtract-time '(13818 19266) '(13818 19145))
     ⇒ (0 121)
     
     (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 '(13818 19266))
     ⇒ 255
     
     (time-to-number-of-days
      (time-since
       (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT")))
     ⇒ 4314.095589286675

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 RFC822 (or similar) date string. For instance: "Sat Sep 12 12:21:54 1998 +0200".

time

An internal Emacs time. For instance: (13818 26466 0 0).

seconds

A floating point representation of the internal Emacs time. For instance: 905595714.0.

days

An integer number representing the number of days since 00000101. For instance: 729644.

decoded time

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

All the examples above represent the same moment.

These are the functions available:

date-to-time

Take a date and return a time.

time-to-seconds

Take a time and return seconds. Note that Emacs has a built-in function, float-time, that does this.

seconds-to-time

Take seconds and return a time.

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.

time-since

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

subtract-time

Take two times and subtract the second from the first. I.e., return the time between the two times.

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.