Next: , Previous: rfc2047, Up: Basic Functions

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.